Git: Distributed Version Control for Code and Documents

Before we use Git to manage files, we need to create a repository for the sample project. The repository will be created locally, so it will only be on the file system of the machine you are working on.

It’s generally recommended that you practice using Git locally first, and only later dive into the decentralized features and functions of Git.

First, Git creates the directory example/ if it doesn’t already exist. Git then initializes an empty repository in this directory and creates a subdirectory .git/ for it, which is used to manage internal data. If the example/ directory already exists, Git creates a new Git repository in it. If both the directory and a repository already exist, Git does nothing. We change to the directory and look at the current state with git status:

Git weist uns darauf hin, dass wir vor dem ersten Commit stehen (Initial commit), hat aber nichts gefunden, was in diesen Commit einfließen könnte (nothing to commit). Dafür liefert es einen Hinweis, welche Schritte sich als nächste anbieten (das tun übrigens die meisten Git-Kommandos): “Erstellen oder kopieren Sie Dateien, und verwenden Sie git add, um diese mit Git zu verwalten.”

Git tells us that we’re about to commit (Initial commit), but hasn’t found anything to commit (nothing to commit). Instead, it gives a hint as to what the next steps should be (most Git commands do that, by the way): “Create or copy files, and use git add to manage them with Git.”

Now let’s give Git a first file to manage, which is a “Hello World!” program in Perl. Of course, you can write any program in the programming language of your choice instead.

We’ll first create the hello.pl file with the following content

and execute the script once:

That means we’re ready to manage the file with Git. But let’s take a look at the output of git status first:

While the first commit is still pending, Git registers that there are already files in that directory, but the system is unaware of them — Git calls them untracked. This is, of course, our little Perl program. To manage it with Git, we use the command git add <file>:

The add generally stands for “add changes” — so you will need it whenever you have edited files, not just when you first add them!

Git doesn’t provide output for this command. Use git status to check if the call was successful:

Git will apply the changes — our new file — at the next commit. However, this commit is not yet complete — we’ve only prepared it so far.

To be precise, we’ve added the file to the Index, an intermediate stage where you collect changes that will be included in the next commit. For further explanation of this concept, see Section 2.1.1, “Index”.

With git status, under Changes to be committed, you can always see which files are in the Index, i.e., will be included in the next commit.

Alles ist bereit für den ersten Commit mit dem Kommando git commit. Außerdem übergeben wir auf der Kommandozeile die Option -m mit einer Commit-Nachricht (Commit Message), in der wir den Commit beschreiben:

Everything is ready for the first commit with the git commit command. We also pass the -m option on the command line with a commit message describing the commit:

Git will confirm that the process has been successfully completed and the file will be managed from now on. The somewhat cryptic output means Git has created the initial commit (root-commit) with the appropriate message. A line has been added to a file, and the file has been created with Unix permissions 0644.⁠^[8]

As you’ve no doubt noticed by now, git status is an indispensable command in your daily work — we’ll use it again here:

Our sample repository is now “clean”, because there are no changes in the Working Tree or Index, nor are there any files that are not managed with Git (untracked files).

To conclude this brief introduction, we’ll introduce you to two very useful commands that you’ll often use to examine the version history of projects.

First, git show allows you to examine a single commit — it’s the most recent one, with no arguments:

You see all relevant information about the commit: the commit ID, the author, the date and time of the commit, the commit message, and a summary of the changes in Unified-Diff format.

By default, git show always prints the HEAD (a symbolic name for the most recent commit), but you could also specify, for example, the commit ID, which is the SHA-1 checksum of the commit, a unique prefix to it, or the branch (master in this case). Thus, the following commands are equivalent in this example:

If you want to view more than one commit, git log is recommended. More commits are needed to demonstrate the command in a meaningful way; otherwise, the output would be very similar to git show, since the sample repository currently contains only a single commit. So let’s add the following comment line to the “Hello World!” program_

Schauen wir uns der Übung halber noch einmal mit git status den aktuellen Zustand an:

For the sake of the exercise, let’s take another look at the current status with git status:

Then, as described in the output of the command, use git add to add the changes to the Index. As mentioned earlier, git add is used both to add new files and to add changes to files already managed.

Then create a commit:

Now git log shows you the two commits:

Git uses aliases to allow you to abbreviate individual commands and even entire command sequences. The syntax is:

To set st as an alias for status:

You can also include options in an alias, for example:

You will find more useful aliases later in the book; how to create more complex aliases is described in Section 8.3.8, “Erweiterte Aliase”. But first, some useful abbreviations:

Very helpful is the color.ui option, which checks whether Git should color the output of various commands. Deleted files and lines will appear red, new files and lines green, commit IDs yellow, and so on. In newer Git versions (1.8.4 and later) this setting is already set automatically, so you don’t need to do anything.

The color.ui option should be set to auto — if Git is output to a terminal, colours are used. If the command is written to a file instead, or the output is piped to another program, Git will not output color sequences, as this could interfere with automatic processing.

Unless set otherwise, Git assumes UTF-8 as the character encoding for all text, especially author names and the commit message. If you want a different encoding, you should configure it explicitly:⁠^[11]

Similarly, the setting i18n.logOutputEncoding determines the character set Git converts names and commit messages to before outputting them.

The encoding of the files managed by Git is not important here and is not affected by these settings — files are only bit streams that Git does not interpret.

Since Git runs on Windows systems like it does on unixoid systems, it has to solve the problem of different line-end conventions. (This only affects text files — binaries that Git recognizes as such are excluded from this treatment).

The core.eol setting, which can take one of the values lf, crlf or native, is mainly relevant for this. The default setting native lets Git use the system default — Unix: Line Feed (lf) only, Windows: Carriage Return & Line Feed (crlf). The file is automatically converted to get line feeds only, but is checked out with CRLF if necessary.

Git can convert between the two types when you check out the file, but it’s important not to mix the two. For this, the core.safecrlf option provides a mechanism to warn the user (value warn) or even disallow the commit (value true).

Eine sichere Einstellung, die auch mit älteren Git-Versionen unter Windows-Systemen funktioniert, ist core.autocrlf auf input zu setzen: Dadurch wird automatisch beim Einlesen der Dateien vom Dateisystem CRLF durch LF ersetzt. Ihr Editor muss dann entsprechend mit LF-Enden umgehen können.

A safe setting, which also works with older Git versions on Windows systems, is to set core.autocrlf to input: This will automatically replace CRLF with LF when reading files from the filesystem. Your editor must then be able to handle LF line endings accordingly.

You can also specify these settings explicitly per file or subdirectory, so that the format is the same across all platforms (see Section 8.1, “Git-Attribute – Dateien gesondert behandeln”).

Git automatically starts an editor, pager, or browser for certain actions. Usually reasonable defaults are used, but if not, you can configure your preferred program with the following options:

A word about the pager: By default, Git uses the less program, which is installed on most basic systems. The command is always started whenever a Git command produces output on a terminal. However, less is automatically configured by an environment variable to quit when the output is completely fit on the terminal. So, if a command produces a lot of output, less will automatically come to the foreground — and remain invisible otherwise.

If core.pager is set to cat, Git will not use a pager. However, this behavior can be achieved from command to command using the --no-pager parameter. In addition, you can use git config pager.diff false to ensure that the output of the diff command is never sent to the pager.

Einige Optionen lassen sich auch durch Umgebungsvariablen überschreiben. Auf diese Weise können in einem Shell-Script oder in einem Alias Optionen lediglich für ein einzelnes Kommando gesetzt werden.

Some options can also be overridden by environment variables. In this way, options can be set in a shell script or alias for a single command only.

The latter variable is useful, for example, if you want to access the version history of another repository within a project without changing directory:

Alternativ können Sie über die Option -c  vor dem Subkommando eine Einstellung nur für diesen Aufruf überschreiben. So könnten Sie zum Beispiel Git anweisen, für den kommenden Aufruf die Option core.trustctime zu deaktivieren:

Alternatively, you can use the -c option before the subcommand to overwrite a setting for this call only. For example, you could tell Git to disable the core.trustctime option for the upcoming call:

The value of the help.autocorrect option determines what Git should do if it can’t find the subcommand you entered, for example if you accidentally type git statsu instead of git status.

If the option is set to a number n greater than zero and Git only finds a subcommand similar to the typed command, this command is executed after n tenths of a second. A value of -1 executes the command immediately. Unset or with the value 0, only the possibilities are listed.

So to correct a typo after one second, set:

You can of course cancel the command during this time with Ctrl+C.

The content of files for Git resides on three levels: the working tree, the index, and the Git repository. The working tree corresponds to the files as they reside on your workstation’s file system — so if you edit files with an editor, search in them with grep, etc., you always operate on the working tree.

The repository is the repository for commits, that is, changes, with author, date, and description. The commits together make up the version history.

Unlike many other version control systems, Git now introduces a new feature, the index. It’s a somewhat elusive intermediate level between the working tree and the repository. Its purpose is to prepare commits. This means that you don’t always have to check in all the changes you have made to a file as commits.

The Git commands add and reset act (in their basic form) on the index, making changes to the index and deleting them again; only the commit command transfers the file to the repository as it is held in the index (Figure 1, “Commands add, reset and commit”).

In the initial state, i.e. when git status outputs the message nothing to commit, the working tree and index are synchronized with HEAD. The index is therefore not “empty”, but contains the files in the same state as they are in the working tree.

Usually, the workflow is then as follows: First, you make a change to the working tree using an editor. This change is transferred to the index by add and finally saved in the repository by commit.

You can display the differences between these three levels using the diff command. A simple git diff shows the differences between the working tree and the index — the differences between the (actual) files on your working system and the files as they would be checked in if you called git commit.

The git diff --staged command, on the other hand, shows the differences between the index (also called the staging area) and the repository, that is, the differences that a commit would commit to the repository. In the initial state, when the working tree and index are in sync with HEAD, neither git diff nor git diff --staged produces output.

If you want to apply all changes to all files, there are two shortcuts: First, the -u or --update option of git add. This transfers all changes to the index, but does not yet create a commit. You can further abbreviate it with the -a or --all option of git commit. This is a combination of git add -u and git commit, which puts all changes to all files into one commit, bypassing the index. Avoid getting into the habit of using these options — they may be handy as shortcuts on occasion, but they reduce flexibility.

But why create commits step-by-step — don’t you always want to check in all changes?

Yes, of course, you usually want to commit your changes completely. However, it can be useful to check them in step by step, for example, to better reflect the development history.

An example: You have worked intensively on your software project for the past three hours, but because it was so exciting, you forgot to pack the four new features into handy commits. In addition, the features are scattered over various files.

At best, you want to be selective, that is, you don’t want to commit all changes from one file, but only certain lines (functions, definitions, tests, …​), and from different files.

Git’s index provides the flexibility you need for this. You collect some changes in the index and pack them into a commit — but all other changes are still preserved in the files.

Wir wollen das anhand des “Hello World!”-Beispiels aus dem vorigen Kapitel illustrieren. Zur Erinnerung der Inhalt der Datei hello.pl:

We’ll illustrate this using the “Hello World!” example from the previous chapter. As a reminder, the contents of the hello.pl file

Now we prepare the file so that it has several independent changes that we don’t want to combine into a single commit. First, we add a shebang line at the beginning.⁠^[13] We also add a line naming the author, and the Perl statement use strict, which tells the Perl interpreter to be as strict as possible in its syntax analysis. It is important for our example that the file has been changed in several places:

With a simple git add hello.pl all new lines would be added to the index — so the state of the file in the index would be the same as in the working tree. Instead, we use the --patch option or short -p.⁠^[14] This has the effect that we are interactively asked which changes we want to add to the index. Git offers us each change one by one, and we can decide on a case-by-case basis how we want to handle them:

This is where Git shows all changes, since they’re very close together in the code. If the changes are far apart or spread across different files, they’re offered separately. The term hunk refers to loosely connected lines in the source code. Some of the options we have at this point include the following:

Die Optionen sind jeweils nur einen Buchstaben lang und schwierig zu merken. Eine kleine Erinnerung erhalten Sie immer durch [?]. Die wichtigsten Optionen haben wir im Folgenden zusammengefasst.

The options are each only one letter long and difficult to remember. A small reminder is always given by [?]. We have summarized the most important options below.

In the example we split the current hunk and enter s for split.

Git confirms that the hunk was successfully split, and now offers us a diff that contains only the shebang line.⁠^[16] We specify y for yes and q for quit on the next hunk. To check if everything worked, we use git diff with the --staged option, which shows the difference between index and HEAD (the latest commit):

To see which changes are not yet in the index, a simple call to git diff is enough to show us that — as expected — there are still two lines in the working tree:

At this point we could create a commit, but for demonstration purposes we want to start from scratch. So we use git reset HEAD to reset the index.

Git confirms and names the files that have changes in them; in this case, it’s just the one.

The git reset command is in a sense the counterpart of git add: Instead of transferring differences from the working tree to the index, reset transfers differences from the repository to the index. Committing changes to the working tree is potentially destructive, as your changes may be lost. Therefore, this is only possible with the --hard option, which we discuss in Section 3.2.3, “Reset and the Index”.

If you frequently use git add -p, it is only a matter of time before you accidentally select a hunk you didn’t want. If the index was empty, this is not a problem since you can reset it to start over. It only becomes a problem if you have already recorded many changes in the index and don’t want to lose them, i.e. you remove a particular hunk from the index without wanting to touch the other hunks.

Analogous to git add -p there is the command git reset -p, which removes single hunks from the index. To demonstrate this, let’s first apply all changes with git add hello.pl and then run git reset -p.

As in the example with git add -p, Git offers hunks one by one, but this time all the hunks in the index. Accordingly, the question is: Unstage this hunk [y,n,q,a,d,/,s,e,?]?, i.e. whether we want to remove the hunk from the index again. As before, by entering the question mark we get an extended description of the available options. At this point we press s once for split, n once for no and y once for yes. Now only the shebang line should be in the index:

A word of warning: A git add -p may tempt you to check in versions of a file that are not executable or syntactically correct (e.g. because you forgot an essential line). So don’t rely on your commit being correct just because make — which works on working tree files! -- runs successfully. Even if a later commit fixes the problem, it will still be a problem, among other things, with automated debugging via bisect (see Section 4.8, “Regressionen finden – git bisect”).

You now know how to exchange changes between working tree, index, and repository. Let’s turn to the git commit command, which you use to “commit” changes to the repository.

A commit keeps track of the state of all the files in your project at any given time, and also contains meta-information:⁠^[17]

In fact, the name of the author does not have to be the name of the committer (who commits). Often, commits are integrated or edited by maintainers (for example, by rebase, which also adjusts the committer information, see Section 4.1, “Commits verschieben – Rebase”). The committer information is usually of secondary importance, though — most programs only show the author and the date the commit was made.

When you create a commit, Git uses the user.name and user.email settings configured in the previous section to identify the commit.

If you call git commit without any additional arguments, Git will combine all changes in the index into one commit, and open an editor to create a commit message. However, the message will always contain instructions commented out with hash marks (#), or information about which files are changed by the commit. If you call git commit -v, you will still get a diff of the changes you will check in, below the instructions. This is especially useful for keeping track of the changes, and for using the auto-complete feature of your editor.

Once you exit the editor, Git creates the commit. If you don’t specify a commit message or delete the entire contents of the file, Git will abort and not create a commit.

If you only want to write one line, you can use the --message option, or short -m, which allows you to specify the message directly on the command line, thus bypassing the editor:

If you want to delete or move files managed by Git, use git rm or git mv. They act like the regular Unix commands, but they also modify the index so that the action is included in the next commit.⁠^[19]

Like the standard Unix commands, git rm also accepts the -r and -f options to recursively delete or force deletion. git mv also offers an option -f (force) if the new filename already exists and should be overwritten. Both commands accept the option -n or --dry-run, which simulates the process and does not modify files.

You will often forget to move a file via git mv or delete it via git rm, and use the standard Unix commands instead. In this case, simply mark the file (already deleted by rm) as deleted in the index, too, using git rm <file>.

To rename the file, proceed as follows: First mark the old file name as deleted using git rm <old-name>. Then add the new file: git add <new-name>. Then check via git status whether the file is marked as “renamed”.

If you want to search for an expression in all files of your project, you can usually use grep -R <expression> ..

However, Git offers its own grep command, which you can call up using git grep <expression>. This command usually searches for the expression in all files managed by Git. If you want to examine only some of the files instead, you can specify the pattern explicitly. With the following command you can find all occurrences of border-color in all CSS files:

The grep implementation of Git supports all common flags that are also present in GNU Grep. However, calling git grep is usually an order of magnitude faster, since Git has significant performance advantages due to the object database and the multithreaded design of the command.

Use git log to examine the project’s version history. The options of this command (most of which also work for git show) are very extensive, and we will introduce the most important ones below.

Without any arguments, git log will output the author, date, commit ID, and the full commit message for each commit. This is handy when you need a quick overview of who did what and when. However, the list is a bit cumbersome when you’re looking at a lot of commits.

If you only want to look at recently created commits, limit git log’s output to n commits with the -<n> option. For example, the last four commits are shown with:

To display a single commit, enter:

The <commit> argument is a legal name for a single commit, such as the commit ID or SHA-1 sum. However, if you do not specify anything, Git automatically uses HEAD. Apart from single commits, the command also understands so-called commit ranges (series of commits), see Section 2.1.7, “Commit-Ranges”.

The -p (--patch) option appends the full patch in Unified-Diff format below the description. Thus, a git show <commit> from the output is equivalent to git log -1 -p <commit>.

If you want to display the commits in compressed form, we recommend the --oneline option: It summarizes each commit with its abbreviated SHA-1 sum and the first line of the commit message. It is therefore important that you include as much useful information as possible in this line! For example, this would look like this:⁠^[20]

The --oneline option is only an alias for --pretty=oneline. There are other ways to customize the output of git log. The possible values for the --pretty option are:

Independently of this, you can display more information about the changes made by the commit below the commit message. Consider the following examples, which clearly show which files were changed in how many places:

So far, we’ve only looked at commands that require only a single commit as an argument, explicitly identified by its commit ID, or implicitly by the symbolic name HEAD, which references the most recent commit.

Das Kommando git show zeigt Informationen zu einem Commit an, das Kommando git log beginnt bei einem Commit, und geht dann so weit in der Versionsgeschichte zurück, bis der Anfang des Repositorys (der sogenannte Root-Commit) erreicht ist.

The git show command displays information about a commit, while the git log command starts at a commit, and then goes back in the version history until the beginning of the repository (called the root commit) is reached.

An important tool for specifying a series of commits is the so-called commit ranges in the form <commit1>..<commit2>. Since we have not yet worked with multiple branches, this is simply a range of commits in a repository, from <commit1> exclusive to <commit2> inclusive. If you omit one of the two boundaries, Git will take the value HEAD.

The command git show or git log -p has been used to show only the difference from the previous commit. If you want to see the differences between several commits, the command git diff.

The diff command performs several tasks. As already seen, you can examine the differences between the working tree and the index without specifying any commits, or the differences between index and HEAD with the --staged option.

However, if you pass two commits or a commit range to the command, the difference between these commits is displayed instead.

SHA-1 is a secure hash algorithm that calculates a checksum of digital information: the SHA-1 sum. The algorithm was introduced in 1995 by the American National Institute of Standards and Technology (NIST) and the National Security Agency (NSA). SHA-1 was developed for cryptographic purposes and is used for checking the integrity of messages and as a basis for digital signatures. Figure 3, “SHA-1 Algorithm” shows how it works, where we calculate the checksum of hello.py.

The algorithm is a mathematical one-way function that maps a bit sequence of maximum length 2⁶⁴-1 bits (about 2 exbibytes) to a checksum of length 160 bits (20 bytes). The checksum is usually represented as a hexadecimal character string of length 40. The algorithm results in 2¹⁶⁰ (approx. 1.5 · 10⁴⁹) different combinations for this length of checksum, and therefore it is very, very unlikely that two bit sequences have the same checksum. This property is called collision safety.

Despite all efforts of cryptologists, several years ago various theoretical attacks on SHA-1 became known, which are supposed to make the generation of collisions possible with a considerable computing effort.⁠^[22] For this reason, NIST today recommends the use of the successors of SHA-1: SHA-256, SHA-384 and SHA-512, which have longer checksums and thus make the generation of collisions more difficult. On the Git mailing list there was a debate about switching to one of these alternatives, but this step was not considered necessary.⁠^[23]

This is because, although there is a theoretical attack vector on the SHA-1 algorithm, this does not compromise the security of Git. In fact, the integrity of a repository is not primarily protected by the collision resistance of an algorithm, but by the fact that many developers have identical copies of the repository.

The SHA-1 algorithm plays a central role in Git because it is used to build checksums of the data stored in the Git repository, the Git objects. This makes them easy to reference as SHA-1 sums of their contents. In your daily work with Git, you will usually only use SHA-1 sums of commits, known as commit IDs. This reference can be passed to many Git commands, such as git show and git diff. Depending on the repository, you often only need to specify the first few characters of an SHA-1 sum, since in practice a prefix is sufficient to uniquely identify a commit.

All data stored in a Git repository is available as Git objects. There are four types:⁠^[24]

Figure 4, “Git Objects” shows three objects from the example project — a blob, a tree, and a commit.⁠^[25] The representation of each object includes the object type, the size in bytes, the SHA-1 sum, and the contents. The blob contains the content of the file hello.py (but not the file name). The tree contains references to one blob for each file in the project, i.e. one for hello.py and one for README, plus one tree per subdirectory, i.e. in this case only one for test. The files in the subdirectories are referenced separately in the respective trees that map these subdirectories.

So the commit object contains exactly one reference to a tree, and that reference is to the tree of the project content — this is a snapshot of the state of the project. The commit object also contains a reference to its direct ancestors, along with the metadata “author” and “committer” and the commit message.

Many Git commands expect a tree as an argument. However, because a commit, for example, references a tree, this is called a tree-ish argument. This refers to any object that can last be resolved to a tree. This category also includes tags (see Section 3.1.3, “Tags — Marking Important Versions”). Similarly, commit-ish is an argument that can be resolved to a commit.

File contents are always stored in blobs. Trees only contain references to blobs and other trees in the form of the SHA-1 sums of these objects. A commit in turn references a tree.

All Git objects are stored in the object database and are identifiable by their unique SHA-1 sum, i.e. you can find an object in the database by its SHA-1 sum once it has been stored. Thus, the object database basically functions like a large hash table, where the SHA-1 sums serve as keys for the stored contents:⁠^[26]

You will first see the four commits that make up the Git repository, including the e2c67eb commit shown in Figure 4, “Git Objects”. This is followed by trees and blobs, each with file or directory correspondence. So-called top-level trees have no directory name: They refer to the top level of a project. A commit always references a top-level tree, so there are four of them.

The hierarchical relationship of the objects listed above is shown in Figure 5, “Hierarchical Relationship of Git Objects”. On the left-hand side, you can see the four commits that are already in the repository, and on the right-hand side, the referenced contents of the most recent commit (C4). As described above, each commit contains a reference to its direct predecessor (the resulting graph of commits is discussed below). This relationship is illustrated by the arrows pointing from one commit to the next.

Each commit references the top-level tree — including the C4 commit in the example. The top-level tree in turn references the files hello.py and README in the form of blobs, and the subdirectory test in the form of another tree. Because of this hierarchical structure and the relationship of the individual objects to one another, Git is able to map the contents of a hierarchical file system as Git objects and store them in the object database.

In a short digression we will go into how to examine the object database of Git. To do this, Git provides so-called plumbing commands, a group of low-level tools for Git, as opposed to the porcelain commands you usually work with. These commands are therefore not important for Git beginners, but are simply intended to give you a different approach to the concept of the object database. For more information, see Section 8.3, “Eigene Git-Kommandos schreiben”.

Let’s first look at the current commit. We’ll use the git show command with the --format=raw option, so let’s output the commit in raw format, so that everything this commit contains is displayed.

As you can see, all the information in Figure 4, “Git Objects” is output: the SHA-1 sums of the commit, tree, and direct ancestor, plus the author and committer (including the date as a Unix timestamp), and the commit description. The command also provides the diff output for the previous commit — but this is not part of the commit, strictly speaking, and is therefore omitted here.

Next, let’s take a look at the tree referenced by this commit, using git ls-tree, a plumbing command to list the contents stored in a tree. It’s similar to ls -l, except that it is in the object database. With --abbrev=7 we shorten the output SHA-1 sums to seven characters.

As in Figure 4, “Git Objects” the tree referenced by the commit contains one blob for each of the two files, and one tree (also: subtree) for the test directory. We can look at its contents again with ls-tree, since we now know the SHA-1 sum of the tree. As expected, you can see that the test tree references exactly one blob, the blob for the file test.sh.

Finally, we make sure that the blob for hello.py really contains our “Hello World!” program and that the SHA-1 sum is correct. The command git show shows any objects. If we pass the SHA-1 sum of a blob, its contents are output. To check the SHA-1 sum we use the plumbing command git hash-object.

A note for curious readers: git hash-object hello.py does not produce the same output as the Unix command sha1sum hello.py. This is because not only the file content is stored in a blob. Instead, the object type, in this case blob, and the size, in this case 67 bytes, are stored in a header at the beginning of the blob. The hash-object command therefore does not calculate the checksum of the file content, but of the blob object.

The four commits that make up the sample repository are shown again in Figure 6, “Repository Content”, but in a different way: The dashed bordered tree and blob objects indicate unchanged objects, all others were added or changed in the corresponding commit. The reading direction here is from bottom to top: at the bottom is C1, which contains only the file hello.py.

Since trees only contain references to blobs and other trees, each commit stores the status of all files, but not their contents. Normally, only a few files change during a commit. New blob objects (and therefore new tree objects) are now created for the new files or those to which changes have been made. However, the references to the unchanged files remain the same.

Even more: A file that exists twice only exists once in the object database. The contents of this file are stored as a blob in the object database and are referenced by a tree in two places. This effect is known as deduplication: Duplicates are not only prevented, but not made possible in the first place. Deduplication is an essential feature of Content-Addressable File Systems, i.e. file systems that know files only by their contents (such as Git, for example, by giving an object the SHA-1 sum of itself as “name”).

Consequently, a repository in which the same 1 MB file exists 1000 times takes up only slightly more than 1 MB. Git essentially has to manage the blob, plus a commit and a tree with 1000 blob entries (20 bytes each plus the length of the filename). A checkout of this repository, on the other hand, consumes about 1 GB of space on the filesystem because Git resolves deduplication.⁠^[27]

The git checkout and git reset commands restore a previous state (see also Section 3.2, “Restoring Versions”): You specify the reference of the corresponding commit, and Git searches for it in the object database. The reference is then used to find the tree object of this commit from the object database. Finally, Git uses the references contained in the tree object to find all other tree and blob objects in the object database and replicates them as directories and files on the file system. This allows you to restore exactly the project state that was saved with the commit at the time.

Because each commit stores its direct ancestors, a graph structure is created. More precisely, the arrangement of the commits creates a Directed Acyclic Graph (DAG). A graph consists of two core elements: the nodes and the edges connecting these nodes. In a directed graph, the edges are also characterized by a direction, which means that when you run the graph, you can only use the edges that point in the appropriate direction to move from one node to the next. The acyclic property rules out that you can find your way back to a node by any route through the graph. So you cannot move in a circle.⁠^[28]

The graph structure is derived from the object model, because each commit knows its direct ancestor (possibly several in the case of a merge commit). The commits form the nodes of this graph — the references to ancestors form the edges.

An example graph is shown in Figure 7, “A Commit Graph”. It consists of several commits, which are colored to make it easier to distinguish between their affiliations to different development branches. First, the commits A, B, C, and D were made. They form the main development branch. Commits E and F contain feature development, which was transferred to the main development branch with commit H. Commit G is a single commit that has not yet been integrated into the main development branch.

One result of the graph structure is the cryptographically secured integrity of a repository. Git uses the SHA-1 sum of a commit to reference not only the contents of the project files at a given point in time, but also all commits executed up to that point, and their relationship to each other, i.e. the complete version history.

The object model makes this possible: each commit stores a reference to its ancestors. These references are then used to calculate the SHA-1 sum of the commit itself. So you get a different commit if you reference another ancestor.

Since the predecessor in turn references predecessors, and its SHA-1 sum depends on the predecessors, and so on, this means that the complete version history is implicitly encoded in the commit ID. Implicit here means: If even one bit of a commit changes anywhere in the version history, then the SHA-1 sum of subsequent commits, especially the topmost one, is no longer the same. The SHA-1 sum doesn’t say anything detailed about the version history, though; it’s just a checksum of it.

Eine Referenz, die Sie selten explizit, aber ständig implizit benutzen, ist HEAD. Sie referenziert meist den gerade ausgecheckten Branch, hier master:

One reference that you rarely use explicitly, but always implicitly, is HEAD. It usually refers to the branch you just checked out, in this case master:

HEAD can also point directly to a commit if you type git checkout <commit-id>. However, you are then in so-called detached-head mode, in which commits may get lost, see also Section 3.2.1, “Detached HEAD”.

The HEAD determines which files are found in the working tree, which commit becomes the predecessor when a new one is created, which commit is displayed by git show, and so on. When we speak of “the current branch”, we mean the HEAD in a technically correct sense.

The simple commands log, show, and diff take HEAD as their first argument, without any further arguments. The output of git log is the same as the output of git log HEAD, and so on — this applies to most commands that operate on a commit if you don’t specify one explicitly. HEAD is thus similar to the shell variable PWD, which specifies “where you are”.

When we talk about a commit, a command usually doesn’t care whether you specify the commit ID in full or in abbreviated form, or whether you access the commit by reference, such as a tag or branch. However, such a reference may not always be unique. What happens if there is a branch master and a tag with the same name? Git checks if the following references exist:

Git will take the first matching reference it finds. So you should always give tags a unique scheme so that they don’t get confused with branches. This way you can address branches directly by name instead of heads/<name>.

Especially important are the suffixes ^ and ~<n>. The syntax <ref>^ indicates the direct ancestor of <ref>. This does not always have to be unique: If two or more branches were merged, the merge commit has several direct ancestors. <ref>^ or <ref>^1 then denotes the first direct ancestor, <ref>^2 the second, and so on.⁠^[30] So the syntax HEAD^^ means “the two-level previous direct ancestor of the current commit”. Note that ^ may have a special meaning in your shell and you may need to protect it with quotes or a backslash.

The syntax <ref>~<n> is equivalent to repeating ^ n times: HEAD~10 thus denotes the tenth direct predecessor of the current commit. Note: This does not mean that only eleven commits are stored between HEAD and HEAD~10: Since ^ only follows the first string in any merge, the eleven commits stored between the two references, and all the other commits integrated by a merge, are the same. The syntax is documented in the git-rev-parse(1) man page in the “Specifying Revisions” section.

A branch is created in Git in no time. All Git needs to do is identify the currently checked out commit and store the SHA-1 sum in the .git/refs/heads/<branch-name> file.

The command is so fast because (unlike other systems) no files need to be copied and no additional metadata needs to be stored. Information about the structure of the version history can always be derived from the commit that a branch references and its ancestors.

Here is an overview of the most important options:

SHA-1 sums are a very elegant solution to describe versions decentrally, but they are semantically poor and unwieldy for humans. Unlike linear revision numbers, commit IDs alone tell us nothing about the order of versions.

During the development of software projects, different “important” versions need to be marked so that they can be easily found in the repository. The most important ones are usually those that are released, called releases. Release candidates are also often marked in this way, i.e. versions that form the basis for the next version and are checked for critical bugs in the course of quality assurance without adding new features. Depending on the project and development model, there are different conventions for marking releases and procedures for preparing and publishing them.

In the open source area, two versioning schemes have become established: the classic major/minor/micro versioning scheme and, more recently, date-based versioning. With major/minor/micro versioning, which is used e.g. with the Linux kernel and also Git, a version is identified by three (often four) numbers: 2.6.39 or 1.7.1. With date-based versioning, on the other hand, the designation is derived from the time of the release, e.g.: 2011.05 or 2011-05-19. This has the great advantage that the age of a version is easily identifiable.⁠^[33]

Git offers tags (“labels”) that can be used to mark any Git object — usually commits — to highlight prominent states in its development history. Like branches, tags are implemented as references to objects. Unlike branches, however, tags are static, meaning that they are not moved when new commits are added, and always point to the same object. There are two types of tags: annotated and lightweight. Annotated tags are tagged with metadata, such as author, description, or GPG signature. Lightweight tags, on the other hand, “simply” point to a specific Git object. For both types of tags, Git creates references under .git/refs/tags/ or .git/packed-refs. The difference is that for each annotated tag, Git creates a special Git object — a tag object — in the Object Database to store the metadata and SHA-1 sum of the selected object, while a Lightweight tag points directly to the selected object. Figure 12, “The Tag Object” shows the contents of a tag object; compare also the other git objects, Figure 4, “Git Objects”.

The tag object shown has both a size (158 bytes) and a SHA-1 sum. It contains the name (0.1), the object type and the SHA-1 sum of the referenced object as well as the name and e-mail of the author, which is called tagger in Git jargon. In addition, the tag contains a tag message that describes the version, for example, and optionally a GPG signature. In the Git project, for example, a tag message consists of the current version designation and the signature of the maintainer.

In the following, let’s first look at how you manage tags locally. Section 5.8, “Exchanging Tags” describes how you exchange tags between repositories.

If you check out a commit that is not referenced by a branch, you are in detached-HEAD mode:

As the explanation, which you can hide by setting the option advice.detachedHead to false, already warns you, changes you make now will be lost in case of doubt: Since your HEAD is the only direct reference to the commit after that, further commits are not directly referenced by a branch (they are unreachable, see above).

So working in detached HEAD mode is especially useful if you want to try something quickly: Has the bug actually already appeared in commit 3329661? Was there actually a README file at the time of 3329661?

If you want to undo all the changes a commit makes, the revert command helps. However, it does not delete a commit, but creates a new one whose changes are exactly the opposite of the other commit: Deleted lines become added lines, and vice versa.

Suppose you have a commit that creates a LICENSE file. The patch of the corresponding commit looks like this:

Now you can undo the changes:

Git creates a new commit on the current branch — unless you specify otherwise — with the description Revert "<Old commit message>". This commit looks like this:

Note that from now on, both the commit and the revert will appear in the version history of a project. You therefore only undo the changes, but do not delete any information from the version history.

You should therefore only use revert if you need to undo a change that has already been published. However, if you are developing locally in a separate branch, it makes more sense to delete these commits completely (see the following section on reset and the topic Rebase, Section 4.1, “Commits verschieben – Rebase”).

If you want to perform a rebase, but not for all changes to the commit, but only for those to a file, you can use this procedure:

The git show command prints the changes from commit 3329661 that apply to the LICENSE file. The -R option causes the unified-diff format to be displayed “the other way around” (reverse). The output is passed to git apply to make the changes to the file and index. The changes are then checked in.

Another way to undo a change is to check out a file from a previous commit, add it to the index, and check it in again:

If you are deleting a commit completely, not just undoing it, use git reset. The reset command sets the HEAD (and thus the current branch), and optionally the index and working tree, to a particular commit. The syntax is git reset [<option>] [<commit>].

The most important types of resets are the following:

If you call git reset without any options, this is equivalent to a git reset --mixed HEAD. We’ve already seen this command: Git sets the current HEAD to HEAD (so it doesn’t change it) and the index to HEAD — in this case, the changes you added before are lost.

The possible uses of this command are many and varied and will reappear in the various command sequences. Therefore it is important to understand the functionality, even if there are sometimes alternative commands that have the same effect.

Suppose you have made two commits to master that you actually want to move to a new branch to work on further. The following command sequence creates a new branch pointing to HEAD, and then resets HEAD and the current branch master two commits. Then check out the new branch <new-feature>.

Alternatively, the following sequence has the same effect: you create a Branch <new-feature> that points to the current commit. Then you delete master and re-create it so that it points to the second predecessor of the current commit.

The two branches, topic and master, that you want to merge, each reference the most recent commit in a chain of commits (F and D), and these two commits in turn reference a tree (corresponding to the top-level directory of your project).

First, Git calculates a so-called merge base, that is, a commit that both of the commits to be merged have as common ancestors. Usually there are several such bases — in the diagram below, A and B — and then the most recent one (which has the other bases as ancestors) is used.⁠^[37] In simple terms, this is the commit where the branches diverged (i.e., B).

Now, if you want to merge two commits (D and F to M), then the trees referenced by the commits must be merged.

Git does this as follows:⁠^[38] If a tree entry (another tree or a blob) is the same in both commits, then that very tree entry will be taken over in the merge commit. This happens in two cases:

If a tree entry disappears in one of the commits, but is still present in the other, and is the same as in the merge base, then it is not taken over. This is equivalent to deleting a file or directory if no changes have been made to the file on the other side. Similarly, if a commit brings a new tree entry, it is copied to the merge tree.

Now what happens if a file from the commits has different blobs, that is, the file has been changed at least on one side? In the event that one of the blobs is the same as in the merge base, only one side of the file has been changed, so Git can simply adopt those changes.

However, if both blobs are different from the merge base, you might run into problems. First, Git tries to apply the changes on both sides.

A 3-way merge algorithm is usually employed for this purpose. Unlike the classic 2-way merge algorithm, which is used when you have two different versions A and B of a file and want to merge them, this 3-way algorithm involves a third version C of the file, extracted from the above merge base. Therefore, because a common ancestor of the file is known, the algorithm can in many cases better (that is, not only based on the line number or context) decide how to merge changes. In practice, so many trivial merge conflicts are already solved automatically without user intervention.

However, there are conflicts that no merge algorithm, no matter how good, can merge. This happens, for example, if the context in version A of the file was changed just before a change in file B, or, worse still, version A and B and C have different versions of a line.

Such a case is called a merge conflict. Git merges all the files as best it can, and then presents the conflicting changes to the user so they can manually merge them (and thus resolve the conflict) (see Section 3.4, “Resolving Merge Conflicts”).

Although it is basically possible to generate a syntactically correct resolution with an algorithm that is specially designed for the respective programming language, an algorithm cannot look beyond the semantics of the code, i.e., cannot grasp the meaning of the code. Therefore, a solution generated in this way would usually not make sense.

The git merge command does not always create a merge commit. A trivial case, but one that does occur frequently, is the so-called fast-forward merge, i.e. a fast forward merge of the branch.

A fast forward merge occurs when a branch, for example topic, is the child of a second branch, master:

A simple git merge topic in Branch master now causes master to simply be moved forward — no merge commit is created.

Of course, such a behavior only works if the two branches have not diverged, i.e. if the merge base of both branches is one of the two branches itself, in this case master.

This behavior is often desirable:

There are different opinions on whether changes should always be integrated via fast-forward or whether it is better to create a merge commit, although this is not absolutely necessary. The results are the same in both cases: Changes from one branch are integrated into another.

However, when you create a Merge-Commit, the integration of a feature becomes clear. Consider the following two excerpts from the version history of a project:

In the above case, you cannot easily see which commits were previously developed in branch sha1-caching, that is, they have to do with a specific feature of the software.

In the lower version, however, you can see at first glance that there were exactly four commits on that branch, and that it was then integrated. Since nothing was developed in parallel, the merge commit would in principle be unnecessary, but it does make the integration of the feature clear.

An explicit merge commit is also helpful because you can undo it with a single command. This is useful, for example, if you have integrated a branch but it has bugs: If the code is running in production, it is often desirable to merge the entire change back in until the bug is fixed. Use for this:

Git then produces a new commit that reverses any changes made by the merge. The -m 1 option here specifies which “side” of the merge should be considered the mainline, or stable line of development: its changes are preserved. In the above example, -m 1 would cause the changes made by the four commits from branch sha1-caching, the second string of the merge, to be undone.

Git has five different merge strategies, some of which can be further adjusted by strategy options. You determine the strategy by -s, so a merge call is as follows:

Some of these strategies can only merge two branches, others any number.

The default strategy recursive knows several options that adjust the behavior especially with regard to conflict resolution. You specify them with the option -X; the syntax is:

If you only merge two branches, you do not need to explicitly specify the recursive strategy by -s recursive.

Since the strategy can only merge two branches, it is possible to speak of our version and theirs: our version is the checked-out branch in the merge process, while their version references the branch you want to integrate.

In the case of non-trivial merge conflicts, a merge tool is recommended that visualizes the three stages of a file accordingly, thereby facilitating the resolution of the conflict.

Common IDEs and editors such as Vim and Emacs offer such a mode. There are also external tools such as KDiff3⁠^[41] and Meld.⁠^[42] The latter visualizes particularly well how a file has changed between commits.

You launch such a merge tool via git mergetool. Git will go through all the files that contain conflicts and display each one (when you press enter) in a merge tool. By default this is Vimdiff.⁠^[43]

Such a program will usually display the three versions of a file — our page, their page, and the file merged as far as possible, including conflict markers — in three columns side by side, the latter sensibly in the middle. It is always essential that you make the change (conflict resolution) in the middle file, i.e. in the working copy. The other files are temporary and are deleted again when the merge tool is finished.

In principle, you can use any other tool. The mergetool script simply stores the three stages of the file with the corresponding file name and starts the diff tool on these three files. If it quits again, Git checks to see if there are any conflict markers left in the file — if not, Git will assume that the conflict was resolved successfully and automatically add the file to the index using git add. Finally, when you have finished processing all the files, you only need to make one commit call to seal the conflict resolution.

The merge.tool option determines which tool Git starts on the file. The following commands are already preconfigured, meaning that Git already knows in which order the program expects the arguments and which additional options need to be specified:

To use your own merge tool, you must set merge.tool to a suitable name, for example mymerge, and then at least specify the mergetool.mymerge.cmd option. The shell evaluates the expression stored in it, and the variables BASE, LOCAL, REMOTE, and MERGED, which are contained in the file with the conflict markers, are set to the corresponding temporary files. You can further configure the properties of your merge command, see the git-config(1) man page in the mergetool configuration section.

Git has a relatively unknown (and poorly documented), but very helpful feature: Rerere, short for Reuse Recorded Resolution. You need to set the rerere.enabled option to true to have the command called automatically (note the d at the end of enabled).

The idea behind Rerere is simple but effective: Whenever a merge conflict occurs, Rerere automatically records a pre-image, an image of the conflict file including markers. In the case of the example above, it would look like this:

If the conflict is resolved as above and the solution is checked in, Rerere saves the conflict resolution:

So far Rerere has not really helped. But now we can delete the merge commit completely (and are back to the situation before the merge). Then we execute the merge again:

Rerere notices that the conflict is known and that a solution has already been found.⁠^[44] So Rerere calculates a 3-way-merge between the saved pre-image, the saved solution and the version of the file in the working tree. This way Rerere can resolve not only the same conflicts, but also similar ones (if in the meantime further lines outside the conflict area have been changed).

The result is not directly added to the index. The solution is simply copied to the file. You can then use git diff to check whether the solution looks useful, run tests if necessary, etc. If everything looks good, you can use the automatic solution via git add as usual.

Decentralized version control systems generally manage merges much better than central ones. This is mainly due to the fact that it is common practice in decentralized systems to check in many small changes locally first. This avoids “monster commits”, which offer much more potential for conflict. This finer granular development history and the fact that merges are usually data in the version history (as opposed to simply copying the lines of code) mean that decentralized systems do not have to look at the mere contents of files when merging.

Prevention is the best way to minimize merge conflicts. Make small commits! Combine your changes so that the resulting commit makes sense as a unit. Always build Topic Branches on the latest release. Merge from topic branches into “collection branches” or directly into master, not the other way around.⁠^[45] Using Rerere prevents conflicts that have already been resolved from constantly reoccurring.

Obviously, good communication among developers is also important for prevention: If several developers implement different and mutually influencing changes to the same function, this will certainly lead to conflicts sooner or later.

Another factor that unfortunately often leads to unnecessary(!) conflicts is autogenerated content. Suppose you write the documentation of a software in AsciiDoc⁠^[46] or work on a LaTeX project with several contributors: Never add the compiled man pages or the compiled DVI/PS/PDF to the repository! In the autogenerated formats, small changes to the plaintext (i.e. in the Ascii or LaTeX version) can cause large (and unpredictable) changes to the compiled formats that Git will not resolve adequately. Instead, it makes sense to provide appropriate Makefile targets or scripts to generate the files, and possibly keep the compiled version on a separate branch.⁠^[47]

Since the listing of multiple commits is hard to keep track of, we examine a small sample repository with several branches merged together:

We recognize four branches (A-D) and one tag release. We can also display this tree on the console with the appropriate command line options using the log command (branch and tag names are printed in semi-bold for better distinction):

Now we change the above command: instead of the --all option, which puts all commits in the tree, we now specify B (the name of the branch)

We receive all commits that are accessible from B. A commit only knows its predecessor(s) (several if branches are merged). “All commits reachable from B” thus refers to the list of commits from B onwards, up to a commit that has no predecessor (called a root commit).

Instead of one, the command can also accept multiple references. So to get the same output as with the --all option, you must specify references A, B, and D. C can be omitted because the commit is already “collected” on the way from A to the root commit.

Of course, you can also specify an SHA-1 sum directly instead of symbolic references:

If a reference is preceded by a caret (^), this negates the meaning.⁠^[50] So the notation ^A means: not the commits that are accessible from A. However, this switch only excludes these commits, but not the others. So the above log command with the argument ^A will not output anything, because Git only knows which commits should not be displayed. So again, we add --all to list all commits, minus those that are accessible from A:

An alternative notation is available with --not: Instead of ^A you can also write --not A.

Such commands are especially useful for examining the difference between two branches: Which commits are in branch D that are not in A? The command returns the answer:

Because this question is often asked, there is another, more intuitive notation for it: A..D is equivalent to D ^A:

Of course the order is important here: “D without A” is a different set of commits than “A without D”! (Compare also the complete graph.)

In our example there is a tag release. To check which commits from branch D (which could stand for “Development”) are not yet included in the current release, simply specify release..D.

Gitk is a graphical program implemented in Tcl, which is usually packaged by distributors along with the actual Git commands — so you can be sure to find it on almost any system.

It represents individual commits or the entire repository in a three-part view: at the top is the tree structure with two additional columns for author and date, below is a list of changes in unified diff format, and a list of files to restrict the changes displayed.

The graph view is intuitive: Different colors help to distinguish the different version strings. Commits are always blue dots, with two exceptions: The HEAD is highlighted in yellow, and a commit that is not a root commit, but whose predecessor is not displayed, is shown in white.

Branches with an arrowhead indicate that further commits have been made on the branch. However, Gitk hides the branch due to the time distance between commits. A click on the arrowhead will take you to the continuation of the branch.

Branches appear as green labels, the currently checked out branch additionally bold. Tags are shown as yellow arrows.

You can delete or check out a branch with a right click on it. Right-clicking on commits opens a menu in which you can perform actions on the selected commit. The only thing that might be easier to do with Gitk than from the command line is cherry picking, i.e. transferring individual commits to another branch (see also Section 3.5, “Taking over Individual Commits: Cherry Pick”).

Gitk accepts essentially the same options as git log. Some examples:

The first command shows all commits since yesterday that have made changes to a file under the doc/ directory. The second command limits the commits to a specific range, while the third command shows the 100 most recent commits from all branches.

Many users leave gitk open during work. Then it’s important to update the display from time to time so that more recent commits appear. With F5 (Update) you load all new commits and refresh the display of the references. Sometimes, however, if you delete a branch, for example, this is not enough. Although the branch is no longer displayed, there may still be unreachable commits in the GUI as artifacts. The key combination Ctrl+F5 (Reload) completely reloads the repository, which solves the problem.

As an alternative to gitk, you can use the GTK-based gitg or Qt-based qgit on UNIX systems; on an OS X system, for example, you can use GitX; for Windows, you can use GitExtensions. Some IDEs now also have corresponding visualizations (e.g. the Eclipse plugin EGit). Furthermore, you can use full-fledged Git clients like Atlassian SourceTree (OS X, Windows; free of charge), Tower (OS X; commercial) as well as SmartGit (Linux, OS X and Windows; free for non-commercial use).

Betrachten Sie folgende Situation: Der Branch sqlite-support zweigt vom Commit “fixed a bug…​” ab. Der master-Branch ist aber schon weitergerückt, und ein neues Release 1.4.2 ist erschienen.

Nun wird sqlite-support ausgecheckt und neu auf master aufgebaut:

Rebase wendet die drei Änderungen, die durch Commits aus dem Branch sqlite-support eingeführt werden, auf den master-Branch an. Danach sieht das Repository in Gitk wie folgt aus:

Normalerweise wird git rebase immer den Branch, auf dem Sie gerade arbeiten, auf einen neuen aufbauen. Allerdings gibt es eine Abkürzung: Wollen Sie topic auf master aufbauen, befinden sich aber auf einem ganz anderen Branch, können Sie das per

Git macht intern Folgendes:

Beachten Sie die (leider wenig intuitive) Reihenfolge:

Bei einem Rebase kann es zu Konflikten kommen. Der Prozess hält dann mit folgender Fehlermeldung an:

Sie gehen vor wie bei einem regulären Merge-Konflikt (siehe Section 3.4, “Resolving Merge Conflicts”) – git mergetool ist hier sehr hilfreich. Fügen Sie dann einfach die geänderte Datei per git add hinzu und lassen Sie den Prozess per git rebase --continue weiterlaufen.⁠^[54]

Alternativ lässt sich der problematische Commit auch überspringen, und zwar mit dem Kommando git rebase --skip. Der Commit ist dann aber verloren, sofern er nicht in einem anderen Branch irgendwo referenziert wird! Sie sollten diese Aktion also nur ausführen, wenn Sie sicher wissen, dass der Commit obsolet ist.

Wenn das alles nicht weiterhilft (Sie z.B. den Konflikt nicht an der Stelle lösen können oder gemerkt haben, dass Sie gerade den falschen Baum umbauen), ziehen Sie die Notbremse: git rebase --abort. Dies verwirft alle Änderungen am Repository (auch schon erfolgreich kopierte Commits), so dass der Zustand danach genau so ist, wie zu dem Zeitpunkt, als der Rebase-Prozess gestartet wurde. Das Kommando hilft auch, wenn Sie irgendwann vergessen haben, einen Rebase-Prozess zu Ende zu führen, und sich andere Kommandos beschweren, dass sie ihre Arbeit nicht verrichten können, weil gerade ein Rebase im Gang ist.

Rebase ist vor allem sinnvoll, um die Commit-Geschichte eines Projekts einfach und leicht verständlich zu halten. Beispielsweise arbeitet ein Entwickler an einem Feature, hat dann aber ein paar Wochen lang etwas anderes zu tun. Währenddessen ist die Entwicklung im Projekt aber schon weiter vorangeschritten, es gab ein neues Release etc. Erst jetzt kommt der Entwickler dazu, ein Feature zu beenden. (Auch wenn Sie Patches per E-Mail verschicken wollen, hilft Rebase, Konflikte zu vermeiden, siehe dazu Section 5.9, “Patches via E-mail”.)

Für die Versionsgeschichte ist es nun viel logischer, wenn sein Feature nicht über einen langen Zeitraum unfertig neben der eigentlichen Entwicklung “mitgeschleppt” wurde, sondern wenn die Entwicklung vom letzten stabilen Release abzweigt.

Für genau diese Änderung in der Geschichte ist Rebase gut: Der Entwickler kann nun einfach auf seinem Branch, auf dem er das Feature entwickelt hat, das Kommando git rebase v1.4.2 eingeben, um seinen Feature-Branch neu auf dem Commit mit dem Release-Tag v1.4.2 aufzubauen. So lässt sich wesentlich leichter ablesen, welche Unterschiede das Feature wirklich in die Software einbringt.

Auch passiert es jedem Entwickler im Eifer des Gefechts, dass Commits im falschen Branch landen. Da findet sich zufällig ein Fehler, der schnell durch einen entsprechenden Commit behoben wird; aber dann muss direkt noch ein Test geschrieben werden, um diesen Fehler in Zukunft zu vermeiden (ein weiterer Commit), was wiederum in der Dokumentation entsprechend zu vermerken ist. Nachdem die eigentliche Arbeit getan ist, kann man diese Commits mit Rebase an eine andere Stelle im Commit-Graphen “transplantieren”.

Rebase kann auch dann sinnvoll sein, wenn in einem Branch ein Feature benötigt wird, das erst kürzlich in die Software eingeflossen ist. Ein Merge des master-Branches ist semantisch nicht sinnvoll, da dann diese und andere Änderungen untrennbar mit dem Feature-Branch verschmolzen werden. Stattdessen baut man den Branch per Rebase auf einen neuen Commit auf, in dem das benötigte Feature schon enthalten ist, und kann dieses dann in der weiteren Entwicklung nutzen.

Das Konzept von Rebase ist zunächst etwas schwierig zu verstehen. Aber sobald Sie verstanden haben, was damit möglich ist, stellt sich die Frage: Wozu braucht man überhaupt noch ein simples Merge, wenn man doch alles mit Rebase bearbeiten kann?

Wenn Git-Rebase nicht oder kaum angewendet wird, entwickelt sich häufig eine Projektgeschichte, die relativ unüberschaubar wird, weil ständig und jeweils für wenige Commits Merges ausgeführt werden müssen.

Wird Rebase dagegen zu viel angewendet, besteht die Gefahr, dass das gesamte Projekt sinnlos linearisiert wird: Das flexible Branching von Git wird zwar zur Entwicklung genutzt, die Branches werden aber dann reißverschlussartig per Rebase hintereinander(!) in den Veröffentlichungsbranch integriert. Das stellt uns vor allem vor zwei Probleme:

So verspielen Sie die Vorteile des flexiblen Branchings von Git. Die Schlussfolgerung ist, dass Rebase weder zu viel noch zu wenig angewendet werden sollte. Beides macht die Projektgeschichte (auf unterschiedliche Art und Weise) unübersichtlich.

Generell fahren Sie mit den folgenden Faustregeln gut:

Wie schon angesprochen, ändern sich bei einem Rebase zwangsläufig die SHA-1-Summen aller Commits, die “umgebaut” werden. Wenn diese Änderungen noch nicht veröffentlicht wurden, d.h. bei einem Entwickler im privaten Repository liegen, ist das auch nicht schlimm.

Wenn aber ein Branch (z.B. `master`) veröffentlicht⁠^[55] und später per Rebase umgeschrieben wird, hat das unschöne Folgen für alle Beteiligten: Alle Branches, die auf master aufbauen, referenzieren nun die alte Kopie des mittlerweile umgeschriebenen master-Branches. Also muss jeder Branch wiederum per Rebase auf den neuen master aufgebaut werden (wodurch sich wiederum alle Commit-IDs ändern). Dieser Effekt setzt sich fort und kann (je nachdem, wann so ein Rebase passiert und wie viele Entwickler an dem Projekt beteiligt sind) sehr zeitaufwendig zu beheben sein (das trifft vor allem dann zu, wenn Git-Neulinge dabei sind).

Daher sollten Sie immer an folgende Regel denken:

Ausnahmen bilden Konventionen wie persönliche Branches oder pu. Letzterer ist ein Kürzel für Proposed Updates und ist in der Regel ein Branch, in dem neue, experimentelle Features auf Kompatibilität getestet werden. Auf diesen Branch baut sinnvollerweise niemand seine eigene Arbeit auf, daher kann er ohne Probleme und vorherige Ankündigung umgeschrieben werden.

Eine weitere Möglichkeit bieten private Branches, also solche, die zum Beispiel mit <user>/ starten. Trifft man die Vereinbarung, dass Entwickler auf diesen Branches eigene Entwicklung betreiben, aber ihre Features immer nur auf “offiziellen” Branches aufbauen, dann dürfen die Entwickler ihre Branches beliebig umschreiben.

Wird über einen langen Zeitraum an einem Feature entwickelt, und Teile des Features fließen schon in ein Mainstream-Release (z.B. per cherry-pick), dann erkennt das Rebase-Kommando diese Commits und lässt sie beim Kopieren bzw. Neuaufbauen der Commits aus, da die Änderung schon in dem Branch enthalten ist.

So besteht der neue Branch nach einem Rebase nur aus den Commits, die noch nicht in den Basis-Branch eingeflossen sind. Auf diese Weise treten Commits nicht doppelt in der Versionsgeschichte eines Projekts auf. Wäre der Branch einfach nur per Merge integriert worden, so wären mitunter die gleichen Commits mit unterschiedlichen SHA-1-Summen an verschiedenen Stellen im Commit-Graphen vorhanden.

Es gibt Situationen, in denen es von einer Software eine Vanilla-Version (“einfachste Version”) gibt und außerdem eine gewisse Anzahl von Patches, die darauf angewendet werden, bevor die Vanilla-Version ausgeliefert wird. Zum Beispiel baut Ihre Firma eine Software, aber vor jeder Auslieferung an den Kunden müssen (je nach Kunde) einige Anpassungen vorgenommen werden. Oder Sie haben eine Open-Source-Software im Einsatz, diese aber ein wenig an Ihre Bedürfnisse angepasst – jedes Mal, wenn nun eine neue, offizielle Version der Software erscheint, müssen Sie Ihre Änderungen neu anwenden und die Software anschließend neu bauen.⁠^[56]

Um Patch-Stacks zu verwalten, gibt es einige Programme, die auf Git aufbauen, Ihnen aber den Komfort bieten, nicht direkt mit dem Rebase-Kommando arbeiten zu müssen. Beispielsweise erlaubt TopGit⁠^[57] Ihnen, Abhängigkeiten zwischen Branches zu definieren – wenn sich dann in einem Branch etwas ändert und andere Branches hängen davon ab, baut TopGit diese auf Wunsch neu auf. Eine Alternative zu TopGit ist Stacked Git⁠^[58].

Sie mögen sich nun gewundert haben: git rebase <referenz> kopiert immer alle Commits, die zwischen <referenz> und HEAD liegen. Was aber, wenn Sie nur einen Teil eines Branches umsetzen, quasi “transplantieren” möchten? Betrachten Sie folgende Situation:

Sie haben gerade auf dem Branch topic ein Feature entwickelt, als Ihnen ein Fehler aufgefallen ist; Sie haben einen Branch bugfix erstellt und noch einen Fehler gefunden. Rein semantisch hat aber Ihr Branch bugfix nichts mit dem topic-Branch zu tun. Sinnvollerweise sollte er daher vom master-Branch abzweigen.

Wenn Sie nun aber per git rebase master den Branch bugfix neu aufbauen, passiert Folgendes: Alle Knoten, die in bugfix enthalten sind, aber nicht im master, werden der Reihe nach auf den master-Branch kopiert – das sind also die Knoten D, E, F und G. Dabei gehören jedoch D und E gar nicht zum Bugfix.

Hier kommt nun die Option --onto ins Spiel: Sie erlaubt, einen Start- und Endpunkt für die Liste der zu kopierenden Commits anzugeben. Die allgemeine Syntax lautet:

In diesem Beispiel wollen wir nur die Commits F und G (oder auch: die Commits von topic bis bugfix) von oben auf master aufbauen. Daher lautet das Kommando:

Das Ergebnis sieht aus wie erwartet:

Sie haben in Section 2.1, “Git Commands” das Kommando commit --amend kennengelernt, mit dem Sie einen Commit verbessern. Es bezieht sich aber immer nur auf den aktuellen (letzten) Commit. Mit rebase --onto können Sie auch Commits anpassen, die weiter in der Vergangenheit liegen.

Suchen Sie zunächst den Commit heraus, den Sie editieren wollen, und erstellen Sie einen Branch darauf:

Anschließend führen Sie Ihre Änderungen aus, fügen geänderte Dateien mit git add hinzu und korrigieren dann den Commit mit git commit --amend --no-edit (die Option --no-edit übernimmt Meta-Informationen wie die Beschreibung des alten Commits und bietet diese nicht erneut zum Editieren an).

Nun spielen Sie alle Commits aus dem master-Branch von oben auf Ihren korrigierten Commit auf:

Sie kopieren so alle Commits von 21d8691 (exklusive!) bis master (inklusive!). Der fehlerhafte Commit 21d8691 wird nicht mehr referenziert und taucht daher nicht mehr auf. Der Branch fix-master ist nun obsolet und kann gelöscht werden.

Eine äquivalente Möglichkeit, einen Commit zu editieren, haben Sie mit der Aktion edit im interaktiven Rebase (siehe Section 4.2.2, “Commits beliebig editieren”).

Es gibt Situationen, in denen Sie das Standardverhalten von git rebase anpassen müssen. Erstens ist dies der Fall, wenn Sie einen Branch mit Rebase bearbeiten, der Merges enthält. Rebase kann versuchen, diese nachzuahmen statt die Commits zu linearisieren. Zuständig ist die Option -p bzw. --preserve-merges.⁠^[59]

Mit der Option -m bzw. --merge können Sie git rebase anweisen, Merge-Strategien zu verwenden (siehe dafür auch Section 3.3.3, “Merging Strategies”). Wenn Sie diese Strategien anwenden, bedenken Sie, dass Rebase intern Commit für Commit per cherry-pick auf den neuen Branch aufspielt; daher sind die Rollen von ours und theirs vertauscht: theirs bezeichnet den Branch, den Sie auf eine neue Basis aufbauen!

Ein interessanter Anwendungsfall ist daher die Strategie-Option theirs für die Merge-Strategie recursive: Falls Konflikte auftreten, wird den Änderungen aus dem Commit, der kopiert wird, Vorrang gegeben. Ein solches Szenario ist also sinnvoll, wenn Sie wissen, dass es konfliktverursachende Änderungen gibt, sich aber sicher sind, dass die Änderungen des neu aufzubauenden Branches “richtiger” sind als die des Baumes, auf den Sie aufbauen. Wenn Sie topic neu auf master aufbauen, sähe ein solcher Aufruf so aus:

In den Fällen, in denen die recursive-Strategie (Default) den Änderungen aus Commits aus topic den Vorzug gibt, werden Sie einen entsprechenden Hinweis Auto-merging <Commit-Beschreibung> finden.

Eine kleine, sehr nützliche Option, die von Rebase direkt an git apply weitergeleitet wird, ist --whitespace=fix. Sie veranlasst Git, automatisch Whitespace-Fehler (z.B. Trailing-Spaces) zu korrigieren. Falls Sie Merge-Konflikte aufgrund von Whitespace haben (zum Beispiel wegen geänderter Einrückung), können Sie auch die in Section 3.3.4, “Options for the Recursive Strategy” vorgestellten Strategie-Optionen verwenden, um automatisch Lösungen erzeugen zu lassen (zum Beispiel durch Angabe von -Xignore-space-change).

Die Kommandos squash bzw. fixup erlauben es, zwei oder mehr Commits miteinander zu verschmelzen.

Niemand schreibt immer sofort fehlerfreien Code. Häufig gibt es einen großen Commit, in dem Sie ein neues Feature implementiert haben; kurz darauf finden sich kleine Fehler. Was tun? Eine ausführliche Beschreibung, warum Sie aus Unachtsamkeit vergessen haben, eine Zeile hinzuzufügen oder zu entfernen? Nicht wirklich sinnvoll, und vor allem störend für andere Entwickler, die später Ihren Code überprüfen wollen. Schöner wäre es doch, die Illusion zu wahren, dass der Commit gleich beim ersten Mal fehlerfrei war…​

Für jeden Fehler, den Sie finden, machen Sie einen kleinen Commit mit einer mehr oder weniger sinnvollen Beschreibung. Das könnte dann zum Beispiel so aussehen:

Wenn sich einige solche Commits angesammelt haben, starten Sie einen interaktiven Rebase-Prozess über die letzten Commits. Schätzen Sie dazu einfach ab, auf wie vielen Commits Sie arbeiten wollen, und bearbeiten Sie dann beispielsweise per git rebase -i HEAD~5 die letzten fünf.

Im Editor erscheinen die Commits nun in umgekehrter Reihenfolge im Vergleich zur Ausgabe von git log. Ordnen Sie nun die kleinen Bugfix-Commits so an, dass sie unter dem Commit, den sie korrigieren, stehen. Markieren Sie dann die Korrektur-Commits mit squash (oder s), also z.B. so:

Speichern Sie die Datei und beenden Sie den Editor; der Rebase-Prozess startet. Weil Sie squash ausgewählt haben, hält Rebase an, nachdem Commits verschmolzen wurden. Im Editor erscheinen die Commit-Nachrichten der verschmolzenen Commits, die Sie nun geeignet zusammenfassen. Verwenden Sie statt squash das Schlüsselwort fixup oder kurz f, wird die Commit-Nachricht der so markierten Commits weggeworfen – für diese Arbeitsweise also vermutlich praktischer.

Nach dem Rebase sieht die Versionsgeschichte viel aufgeräumter aus:

Wenn Sie die Commit-Nachricht mit fixup! bzw. squash! beginnen, gefolgt vom Anfang der Beschreibung des Commits, den Sie korrigieren wollen, können Sie das Kommando

aufrufen. Die wie oben mit fixup! bzw. squash! markierten Commits werden automatisch an die richtige Stelle verschoben und mit der Aktion squash bzw. fixup versehen. So können Sie den Editor direkt beenden, und die Commits werden verschmolzen. Falls Sie häufig mit dieser Option arbeiten, können Sie dieses Verhalten auch durch eine Konfigurationsoption zum Standard bei Rebase-Aufrufen machen: Setzen Sie dafür die Einstellung rebase.autosquash auf true.

Wenn Sie einen Commit mit edit markieren, kann er beliebig editiert werden. Dabei geht Rebase wie in den anderen Fällen auch sequentiell die Commits durch. Bei den Commits, die mit edit markiert sind, hält Rebase an und HEAD wird auf den entsprechenden Commit gesetzt. Sie können dann den Commit ändern, als wäre er der aktuellste im Branch. Anschließend lassen Sie Rebase weiterlaufen:

Im Wesentlichen erreichen Sie dabei dasselbe wie im Beispiel git rebase --onto in Section 4.1.9, “Einen Commit verbessern” — allerdings können Sie auch weit kompliziertere Aktionen ausführen. Einen häufigen Anwendungsfall beschreibt folgendes “Rezept”.

Eine bequeme Alternative zu git blame auf der Konsole bietet das grafische Tool git gui blame (hierfür müssen Sie gegebenenfalls das Paket git-gui installieren).

Wenn Sie eine Datei per git gui blame <datei> untersuchen, werden die unterschiedlichen Blöcke, die aus verschiedenen Commits stammen, mit Grautönen hinterlegt dargestellt. Links sehen Sie die abgekürzte Commit-ID sowie die Initialen des Autors.

Erst wenn Sie mit der Maus über einen solchen Block fahren, erscheint ein kleines Popup-Fenster mit Informationen zum Commit, der die Zeilen geändert hat, möglicherweise auch mit einer Mitteilung, aus welcher Datei und welchem Commit dieser Codeblock verschoben oder kopiert wurde.

Bei der Code-Review interessiert man sich häufig dafür, wie eine Datei eigentlich vor einer bestimmten Änderung aussah. Dafür bietet das grafische Blame-Tool die folgende Möglichkeit, in der Versionsgeschichte zurückzugehen: Klicken Sie mit der rechten Maustaste auf die Commit-ID eines Code-Blocks und wählen Sie im Kontextmenü Blame Parent Commit aus – nun wird der Vorgänger dieser Änderung angezeigt. Sie können auf diese Weise mehrere Schritte zurückgehen. Über den grünen Pfeil links oben können Sie wieder in die Zukunft springen.

Die Syntax für Muster ist der Shell-Syntax nachempfunden:

Ein Beispiel:⁠^[60]

Dateien, die bereits versioniert sind, werden nicht automatisch ignoriert. Um eine solche Datei trotzdem zu ignorieren, weisen Sie Git explizit an, die Datei zu “vergessen”:

Um die Datei mit dem nächsten Commit zu löschen, aber trotzdem im Working Tree vorzuhalten:

Dateien, die bereits ignoriert werden, erscheinen in der Ausgabe von git status nicht. Außerdem weigert sich git add, die Datei zu übernehmen; mit der Option --force bzw. -f zwingen Sie Git, die Datei doch zu beachten:

Das Kommando git clean löscht ignorierte sowie unbekannte (sog. untracked) Dateien. Da evtl. Dateien unwiederbringlich verlorengehen könnten, verfügt das Kommando über die Option --dry-run (bzw. -n); sie gibt Auskunft, was gelöscht würde. Als weitere Vorsichtsmaßnahme weigert sich das Kommando, irgendetwas zu löschen, außer Sie übergeben explizit die Option --force bzw. -f.⁠^[61]

Standardmäßig löscht git clean nur die unbekannten Dateien, mit -X entfernt es nur die ignorierten Dateien und mit -x sowohl unbekannte als auch ignorierte. Mit der Option -d werden zusätzlich Verzeichnisse gelöscht, die in Frage kommen. Um also unbekannte sowie ignorierte Dateien und Verzeichnisse zu löschen, geben Sie ein:

Mit git stash speichern Sie den aktuellen Zustand von Working Tree und Index, sofern diese sich von HEAD unterscheiden:

Mit der Option --keep-index bleibt der Index intakt. Das heißt, alle Veränderungen die bereits im Index sind, bleiben im Working Tree und im Index vorhanden und werden zusätzlich im Stash gespeichert.

Die Veränderungen am Working Tree sowie dem Index werden ``beiseite geschafft__, und Git erzeugt keinen Commit auf dem aktuellen Branch. Um den gespeicherten Zustand wieder herzustellen, also um den gespeicherten Patch auf dem aktuellen Working Tree anzuwenden und gleichzeitig den Stash zu löschen, verwenden Sie:

Sie können zwischen dem Abspeichern und dem Wiederherstellen das Repository beliebig verändern, z.B. den Branch wechseln, Commits machen usw. Der Stash wird immer auf den aktuellen Working Tree angewendet.

Das Kommando git stash pop ist eine Abkürzung für die zwei Kommandos git stash apply (Stash anwenden) und git stash drop (Stash verwerfen):

Sowohl pop als auch apply pflegen die Veränderungen in den Working Tree ein, der Zustand des Index wird nicht wieder hergestellt. Mit der Option --index stellen Sie auch den abgespeicherten Zustand des Index wieder her.

Es kann zu Konflikten kommen, wenn Sie einen Stash auf einem anderen Commit anwenden als dem, auf dem er entstanden ist:

In dem Fall verwenden Sie die üblichen Rezepte zum Lösen des Konflikts, siehe Section 3.4, “Resolving Merge Conflicts”. Wichtig ist aber, dass die Konflikt-Marker die Bezeichnungen Updated Upstream (die Version im aktuellen Working Tree) sowie Stashed Changes (Veränderungen im Stash) tragen:

Der Stash wird per Default auf den aktuellen Working Tree angewendet, vorausgesetzt dieser ist sauber – wenn nicht, bricht Git ab:

Git schlägt zwar vor, dass Sie die Änderungen dem Index hinzufügen, wie Sie aber vorgehen sollten, hängt von Ihrem Ziel ab. Wenn Sie die Änderungen im Stash zusätzlich zu denen im Working Tree haben wollen, bietet sich Folgendes an:

Zur Erläuterung: Zuerst werden die noch nicht gespeicherten Veränderungen am Working Tree dem Index hinzugefügt; dann die Veränderungen aus dem Stash herausgeholt und auf den Working Tree angewendet, und zuletzt noch der Index zurückgesetzt.

Alternativ dazu können Sie auch einen zusätzlichen Stash erstellen, und die Veränderungen, die Sie haben wollen, auf einen sauberen Working Tree anwenden:

Bei diesem Rezept verwenden Sie mehrere Stashes. Zuerst lagern Sie die Veränderungen am Working Tree in einen neuen Stash aus, dann holen Sie die Veränderungen, die Sie eigentlich haben wollen, aus dem vorherigen Stash und löschen diesen nach der Anwendung.

Standardmäßig setzt Git für einen Stash die folgende Nachricht:

Meist reicht dies aus, um einen Stash zu identifizieren. Wenn Sie vorhaben, Ihre Stashes länger vorzuhalten (möglich, aber nicht wirklich zu empfehlen), oder wenn Sie mehrere machen wollen, raten wir, diese mit einer besseren Anmerkung zu versehen:

Git verwaltet alle Stashes als Stack, d.h. aktuellere Zustände liegen oben auf und werden zuerst verarbeitet. Die Stashes sind mit einer Reflog-Syntax (siehe auch Section 3.7, “Reflog”) benannt:

Erzeugen Sie einen neuen Stash, wird dieser als stash@{0} bezeichnet und die Nummer der anderen wird inkrementiert: Aus stash@{0} wird stash@{1}, aus stash@{1} wird stash@{2} usw.

Geben Sie keinen expliziten Stash an, beziehen sich die Kommandos apply, drop und show auf den neuesten, also stash@{0}.

Um einzelne Stashes einzusehen, verwenden Sie git stash show. Standardmäßig druckt dieses Kommando eine Bilanz der hinzugefügten und entfernten Zeilen aus (wie git diff --stat):

Das Kommando git stash list gibt eine Liste der derzeit angelegten Stashes aus:

Einzelne Stashes löschen Sie mit dem Kommando git stash drop, alle mit git stash clear. Sollten Sie versehentlich einen Stash löschen, finden Sie diesen nicht über die üblichen Reflog-Mechanismen wieder! Jedoch gibt folgender Befehl die ehemaligen Stashes aus:⁠^[62]

Außerdem ist wichtig, dass die so gezeigten Einträge nur als unerreichbare Objekte in der Objektdatenbank vorhanden sind und somit auch den normalen Wartungsmechanismen unterliegen — sie werden also nach einiger Zeit gelöscht und nicht dauerhaft vorgehalten.

Git erzeugt für jeden Stash zwei Commit-Objekte, eines für die Veränderungen am Working Tree und eines für die Veränderungen am Index. Beide haben den aktuellen HEAD als Vorfahren, das Working-Tree-Objekt hat das Index-Objekt als Vorfahren. Dadurch wird ein Stash in Gitk als Dreieck angezeigt, was im ersten Moment etwas verwirrend ist:

Mit dem Alias git tree (siehe Section 3.6.1, “Revision Parameters”) sieht das so aus:

Da die Stash-Objekte nicht durch einen Branch referenziert sind, wird das Working-Tree-Objekt mit einer besonderen Referenz, refs/stash, am Leben erhalten. Dies gilt aber nur für den neuesten Stash. Ältere Stashes werden nur im Reflog (siehe Section 3.7, “Reflog”) referenziert und erscheinen deshalb auch nicht in Gitk. Im Gegensatz zu normalen Reflog-Einträgen verfallen gespeicherte Stashes jedoch nicht und werden deshalb auch nicht durch die normalen Wartungsmechanismen gelöscht.

Eine bisect-Sitzung starten Sie mit den folgenden Kommandos:

Sobald Sie die beiden Punkte definiert haben, checkt Git einen Commit in der Mitte aus, Sie befinden sich also ab jetzt im Detached-Head-Modus (siehe Section 3.2.1, “Detached HEAD”). Nachdem Sie überprüft haben, ob die Regression noch immer vorhanden ist, können Sie ihn mit git bisect good bzw. git bisect bad markieren. Git checkt automatisch den nächsten Commit aus.

Möglicherweise können Sie den ausgecheckten Commit nicht testen, z.B. weil das Programm nicht fehlerfrei kompiliert. In diesem Fall können Sie per Git git bisect skip einen anderen Commit in der Nähe auswählen lassen und mit diesem wie gewohnt verfahren. Die Fehlersuche können Sie jederzeit abbrechen per git bisect reset.

Idealerweise können Sie automatisiert testen, ob der Fehler auftritt — mit einem Test, der erfolgreich laufen muss, wenn die Regression nicht auftritt.

Sie können dann wie oben die Punkte good und bad definieren. Danach geben Sie git bisect run <pfad/zum/test> ein.

Anhand des Rückgabewerts entscheidet bisect, ob der überprüfte Commit good ist (wenn das Script sich erfolgreich, d.h. mit Rückgabewert 0 beendet) oder bad (Werte 1—​127). Ein Spezialfall ist der Rückgabewert 125, der ein git bisect skip bewirkt. Wenn Sie also ein Programm haben, das kompiliert werden muss, sollten Sie als erstes ein Kommando wie make || exit 125 einbauen, so dass der Commit übersprungen wird, wenn das Programm nicht richtig kompiliert.

Bisect kann dann ganz automatisch den problematischen Commit identifizieren. Das sieht z.B. so aus:

Git supports several protocols for accessing a remote repository, the most common three being Git protocol, SSH, and HTTP(S). Designed specifically for Git, the Git protocol favors data transfer by always transferring the smallest possible amount of data. It doesn’t support authentication, so it’s often transmitted over an SSH connection. This ensures both efficient (Git protocol) and secure (SSH) transmission. HTTP(S) is used when a firewall is configured very restrictively and the allowed ports are drastically restricted.⁠^[67]

In general, a valid URL contains the transfer protocol, the address of the server and the path to the repository:⁠^[68]

For the SSH protocol the short form still exists:

It is also possible to clone repositories locally using the following syntax:

If you want to know what URLs are configured for a remote repository, use git remote’s --verbose or -v option:

You can see that there are two URLs for the remote repository origin, but they are set to the same value by default. The first URL (fetch) specifies from where and with which protocol changes are downloaded. The second URL (push) specifies where changes are uploaded to and with which protocol. Different URLs are particularly interesting if you download or upload with different protocols. A common example is to download with the git protocol (git://) and upload with the SSH protocol (ssh://). It is then downloaded without authentication and encryption, which provides a speed advantage, but uploaded with authentication and encryption, which ensures that only you or other authorized people can upload. You can use the git remote set-url command to customize the URLs:

The current status of the remote repository is stored locally. Git uses the mechanism of remote tracking branches, special branches — local references — that reflect the state of the remote branches. They “track” the remote branches and are advanced or set by Git when synchronizing with the remote, if the branches in the remote have changed. In terms of the commit graph, remote tracking branches are markers within the graph that point to the same commits as the branches in the remote repository. You can’t modify remote tracking branches like normal branches; Git manages them automatically, so it updates them. When you clone a repository, Git initializes a remote tracking branch for each remote branch.

Figure 31, “Generated Remote Tracking Branches” shows an example. The origin remote repository has three branches: pu, maint, and master. Git creates a remote tracking branch in the cloned repository for each of these remote branches. It also creates a local branch master in the clone that corresponds to the remote branch master. This is checked out and is the branch you should work in if you plan to upload commits to the master (but see Section 5.3.1, “git fetch”).

In the git fetch example, there is only one branch on the remote side, master. That’s why Git creates only one remote tracking branch in the clone, origin/master. The git branch -r command shows all remote tracking branches:

The special entry origin/HEAD → origin/master states that in the remote repository the HEAD points to the branch master. This is important for cloning, because this branch is checked out after cloning. The list of remote tracking branches is a bit sparse in this example, you can see more entries in a clone of the Git-via-Git repository:

All branches can be displayed with git branch -a:

In this case, Git uses the prefix remotes/ to clearly distinguish remote tracking branches from normal ones. If you have enabled color output, the different branches will also be color-coded: the checked-out branch green, remote tracking branches red.

Remote Tracking Branches are also references only and are therefore stored under .git/refs like all references. However, since they are special references that are also linked to a remote repository, they end up under .git/refs/remotes/<remote-name> (see Section 3.1.1, “HEAD and Other Symbolic References”). In Gitk, the remote tracking branches are displayed with the prefix remotes/<remote-name>/, which is also colored dark yellow (Figure 32, “Branch next and the corresponding remote tracking branch in Gitk”).

As soon as new commits are created by other developers in a remote, you want to download them to your local repository. In the simplest case, you just want to find out which commits you don’t have locally, download them, and update the remote tracking branches so that they reflect the current status in the remote.

Use the git fetch command to do this:

Git acknowledges the call with a message that origin/master has been set from commit 79170e8 to commit 003e3c7. The notation master → origin/master indicates that the branch master from the remote was used to update the remote tracking branch origin/master. In other words: Branches from the remote on the left and remote tracking branches on the right.

See <<fig.fetch> for the effect this has on the commit graph: On the left side is the initial state of the remote origin and next to it that of the clone. Both the remote and the clone have new commits since the last synchronization (C and D). The remote tracking branch origin/master in the clone points to commit B; this is the last state of the remote known to the clone. By calling git fetch origin, Git updates the remote tracking branch in the clone to reflect the current status of the master (pointing to commit C) in the remote. To do this, Git downloads the missing commit C and then sets the remote tracking branch on it.

Suppose you want to transfer commits from the remote repository to your local branch. To do this, first run a git fetch to fetch new commits, and then merge the change from the corresponding remote tracking branch:⁠^[71]

For this use case, Git provides the git pull command to speed up your workflow. It is a combination of git fetch and git merge or git rebase.

Downloading new commits from origin and merging all commits referenced by the master there into the current branch can be done with the following command:

In Figure 34, “What happens with a pull” we illustrate the process. On the left, you see the remote repository origin and next to it the current status of the local repository. The repository was cloned when it only contained commits A and B, so the remote tracking branch points origin/master to B. In the meantime, both the remote (C) and local (D) repositories have been added.

On the right side is the state after git pull origin master. Commit C has been added to the local repository. The fetch call contained in the pull has updated the remote tracking branch, i.e. it points to the same commit as the master in origin and thus reflects the state there. In addition, the merge call contained in the pull has integrated the master from origin into the local master, as you can see from the merge commit M and the current position of the local master.

Alternatively, the --rebase option instructs the pull command to rebase the local branch to the remote tracking branch after fetch:

In Figure 35, “What happens during a pull with rebase” you can see what happens if you perform a rebase instead of the default merge.

The initial situation is the same as in Figure 34, “What happens with a pull”. The fetch contained in the pull moves the remote tracking branch origin/master to commit C. However, rebase does not create a merge commit; instead, a call to rebase gives the commit D a new base, and the local master is set to the new commit D'. (Rebase is described in detail in Section 4.1, “Commits verschieben – Rebase”).

Git beginners often ask themselves whether they should use fetch or pull. The answer depends on how you develop: How big is the project? How many remotes are there? How heavily are branches used?

There are two ways to delete references in the remote: The older one (before Git version 1.7.0) is to omit the local reference in the refspec — this statement means you want to upload “nothing”. So you replace an existing reference with the empty one.

However, newer git versions usually use the git push command with the --delete option, which is syntactically much clearer:

Note that in other clones, the remote tracking branch origin/bugfix, if present, does not automatically disappear! See the section on pruning above (Section 5.3, “Downloading Commits”).

In everyday life you often run git push without specifying remote and refspec. In this case, Git uses the configuration entries (upstream branch and push.default) to decide which references are sent where.

By default, Git proceeds like this:⁠^[73] If you don’t specify a remote, Git will look for the upstream configuration of the current branch. If the name of the branch on the remote side matches the name of the local branch, the corresponding reference is uploaded (this is to protect you from uploading, for example, your branch devel to master if the upstream configuration is incorrect). If no upstream branch is configured, Git aborts with an error message:

If you use git push <remote> to specify a remote but no branch, Git will attempt to upload the current branch to the remote under the same name.

The strategy described here is also known as simple. For most use cases, it does what the user expects and protects against avoidable errors. However, you can set the push.default option responsible for this to one of the following values if required:

In some cases, Git will automatically configure upstream branches (for example, after a git clone). However, you need to do this explicitly, especially for new branches that you are uploading for the first time. You can do this either afterwards using the --set-upstream-to option or, in short, -u of git branch:

Alternatively, and if you think about it, you can also have git push write the configuration when you call git push with the -u option:

To view the upstream configuration of your branches, call git branch -vv. The output shows the upstream partner of a branch (if any) in square brackets.

The git remote show command gives a concise summary of the remote, including the branches available there, whether they are tracked locally (tracking status) and which local branches are configured for specific tasks.

The command must request the current status from the remote, i.e. the command fails if the remote is not available, e.g. due to a missing network connection. The option -n prevents the query.

If you have configured an upstream branch, when you change the branch (git checkout) and query the status (git status), you will receive a notification about the status of the branch compared to the upstream, for example:

Here there are four different possibilities:

With the -v (compare only) or -vv (compare and upstream name) option, git branch displays the appropriate information for local branches:

The command prints the SHA-1 prefix for all branches and the commit message of the current commit. If an upstream is configured for the branch, Git returns both the name and a comparison to the upstream. In the example, you see four different branches. master has an additional commit that has not yet been uploaded to the remote, and is therefore ahead. The branch feature, on the other hand, has no upstream branch configured, so it currently exists only locally. The branch next is up-to-date with the corresponding remote tracking branch. The Branch pu, on the other hand, “lags” behind its upstream and is therefore displayed as behind. The only state missing here is diverged — then both ahead and behind are shown including the number of “missing” commits.

To generate a pull request automatically, there is the git command request-pull. The syntax is:

As <URL> you specify your public repository (either as the actual URL or as a configured remote repository), and as <start> you select the reference on which the feature is built (in many cases the branch master, which should match the master branch of the official repository). Optionally, you can specify an <end>; if you omit this, Git will use HEAD.

The output is by default STDOUT, and includes the repository’s URL and branch name, a short description of all commits by author, and a diff state, i.e., a balance of added and deleted lines by file. This output can easily be forwarded to an e-mail program. If you add the -p option, a patch with all changes is appended below the text.

For example, to ask someone to download the two latest commits from a repository:

In principle, Git automatically downloads new tags when you call git fetch or git pull. That is, if you download a commit that has a tag pointing to it, that tag will be included. However, if you use a refspec to exclude individual branches, then commits in those branches will not be downloaded, and thus no tags that may point to those commits will be downloaded. Conclusion: Git only downloads relevant tags. With the options --no-tags (no tags) and --tags or -t (all tags) you can adjust the default behavior. Note, however, that --tags not only downloads the tags, but necessarily the commits to which they point.

Git notifies you when new tags arrive:

If you want to know what tags are present on the remote side, use git ls-remote with the --tags option. For example, you can get all release candidates of git version 1.7.1 with the following call:

Git outputs the SHA-1 sums of the tags and their contents.⁠^[75]

Git does not automatically upload tags. You need to pass them explicitly to git push, similar to the branches, e.g. to upload the tag v0.1:

If you want to upload all tags at once, use the --tags option. But be careful: Avoid this option if you use Annotated Tags to mark versions and Lightweight Tags to mark something locally, as described in Section 3.1.3, “Tags — Marking Important Versions”, because with this option you would upload all tags, as already mentioned.

Attention: Once you have uploaded a tag, you should never change it! The reason: Let’s say Axel changes a tag, like v0.7, that he has already released. First it pointed to the 5b6eef commit, and now to bab18e. Beatrice had already downloaded the first version pointing to 5b6eef, but Carlos had not yet. The next time Beatrice calls git pull, Git won’t download the new version from the v0.7 tag; the assumption is that tags don’t change, so Git doesn’t check the validity of the tag! When Carlos now runs git pull, he also gets the v0.7 tag, but it now points to bab18e. Finally, two versions of the tag — each pointing to different commits --- are in circulation. Not a very helpful situation. It gets really confusing when both Carlos and Beatrice use the same public repository, and upload all tags by default.⁠^[76] The tag “jumps” back and forth between two commits in the public repository, so to speak; which version you get with a clone depends on who pushed last.

If you do get this mishap, you have two options:

The git format-patch command exports one or more commits as patches in Unix mailbox format and prints one file per commit. The file names consist of a sequential numbering and the commit message, and end in .patch.⁠^[77] As an argument, the command expects either a single commit or a range such as A..B. If you specify a single commit, Git will evaluate this as the selection from the commit to the HEAD.

Figure 38, “Formatting three commits to 'master' as patches” shows the initial situation. We want to export the three commits in the fix-git-svn-docs branch, that is, all commits from master, as patches:

The generated files contain, among other things, the header fields From, Date and Subject, which are used for sending as e-mail. These fields are completed using the information available in the commit — author, date, and commit message. The files also contain a diff-stat summary and the changes themselves as a patch in unified diff format. The [PATCH m/n] suffix⁠^[78] in the subject line is used later by Git to apply the patches in the correct order.

A corresponding excerpt follows:

If you plan to send a series of patches, it is recommended that you use the --cover-letter option to create a kind of “cover page” in which you describe the series. By default the file is called 0000-cover-letter.patch. Apart from the default headers, such a file looks like this:

As you can see, the Subject: still has the prefix [PATCH 0/3]; this way, all recipients can immediately see that it is a cover page. The file also contains the output of git shortlog and git diff --stat. Replace * SUBJECT HERE with a subject and BLURB HERE * with a summary of the patch series. Send the file together with the patch files.

Send the generated files with git send-email (or an email client of your choice). The command expects as its only mandatory argument either one or more patch files, a directory full of patches, or a selection of commits (in which case Git also calls git format-patch internally):

The command git send-email sets the fields Message-Id and In-Reply-To. This makes all e-mails after the first one look like replies to them and thus most mail programs will display them as a continuous thread:⁠^[79]

You can customize the command with options such as --to, --from and` --cc` (see the git-send-email(1) man page). However, if not specified, the essential information is queried interactively — most important is an address to which the patches should be sent.⁠^[80]

Before the emails are actually sent, you will see the header again; you should check if everything is as you want it, and then answer the question` Send this email? ([y]es|[n]o|[q]uit|[a]ll):` answer with y for “yes”. To get familiar with the command, you can first send all emails only to yourself or use the --dry-run option.

If you want to use your preferred Mail User Agent (MUA) (e.g. Thunderbird, Kmail or others) to send patches, there may be a few things to consider. Some MUAs are notorious for mutilating patches so that Git won’t recognize them as such.⁠^[83]

Patch emails exported with git format-patch are translated back into commits by the git command git am (apply from mailbox). A new commit is created from each email, and its meta-information (author, commit message, etc.) is generated from the email header lines (From, Date). As mentioned earlier, Git uses the number in the subject to determine the order in which the commits should be entered. To complete the example from earlier: If the emails are in the Maildir directory patches, then that’s enough:

When you apply patches from others using git am, the values of Author/AuthorDate and Committer/CommitDate are different. This means that both the author of the commit and the person who commits it are honored. In particular, the attributes are retained; it remains traceable who wrote which lines of code. With Gitk, the author and committer values are displayed by default; on the command line, set the --format=fuller option, which is accepted by git log and git show, among others:

With the Dictator and Lieutenants Workflow (Section 5.10, “A Distributed, Hierarchical Workflow”), it can happen that more than two people are involved in a commit. In this case, it makes sense that everyone who reviews the patch also “approves” it, especially the author. For this purpose, there is a --signoff option (-s for short) for the git commit and git am commands, which appends the committer’s name and email to the commit message:

This feature is especially useful for larger projects, which usually have guidelines on how to format commits and how best to send them.⁠^[84]

Conflicts can occur when patches are entered with git am, e.g. if the patches are based on an older version and the lines concerned have already been changed. In this case, the process is interrupted and you then have several options for how to proceed. Either resolve the conflict, update the index and continue the process with git am --continue, or skip the patch with git am --skip. Use git am --abort to abort the process and restore the current status of the branch.

Because patches usually contain changes made by others, it can sometimes be difficult to find the right solution to a conflict. The best strategy for patches that cannot be applied is to ask the author of the patches to rebase them to a well-defined base, such as the current master, and send them again.

Submodules werden von Git als Unterverzeichnisse verwaltet, die einen speziellen Eintrag in der Datei .gitmodules besitzen. Zuständig für den Umgang mit ihnen ist das Kommando git submodule.

Zunächst müssen wir die Bibliothek importieren. Das geschieht mit dem folgenden Kommando:

An der Ausgabe von git status können wir nun erkennen, dass ein neues Verzeichnis libgit2 vorliegt, sowie die Datei .gitmodules mit folgendem Inhalt erstellt wurde:

Diese Datei wurde auch schon dem Index hinzugefügt, also für den Commit vorbereitet. Das Verzeichnis libgit2 hingegen taucht in der Ausgabe von git diff --staged nicht wie gewohnt auf:

Anstatt alle Dateien des Verzeichnisses aufzulisten, speichert Git eine “spezielle” Datei (erkennbar an dem unüblichen Datei-Modus 160000), die lediglich den Commit, auf dem das Modul gerade steht, festhält.

Wir importieren diese Änderungen und können von nun an die libgit2 in ihrem Unterverzeichnis kompilieren und dann gegen sie linken:

Das übergeordnete Projekt und die libgit2 sind nun im Working Tree zusammengeführt — ihre Versionsgeschichte aber ist und bleibt getrennt. In dem Git-Repository der libgit2 können Sie sich genau so verhalten wie in einem “echten” Repository. Sie können sich zum Beispiel die Ausgabe von git log in dem übergeordneten Projekt und nach einem cd libgit2 in dem Submodule anschauen.

Im Gegensatz zu Submodules, die ihren Charakter als eigenständiges Git-Repository wahren, verschmelzen Sie die Geschichte zweier Projekte direkt, wenn Sie mit Subtrees arbeiten. Eine Gegenüberstellung beider Ansätze folgt im Anschluss.

Im Wesentlichen basiert diese Technik auf sogenannten Subtree-Merges, auf die schon kurz in Section 3.3.3, “Merging Strategies” über Merge-Strategien eingegangen wurde. In unserem Beispiel erfolgt ein Subtree-Merge, indem reguläre Commits aus dem Repository der libgit2 unterhalb des Trees (Verzeichnisses) libgit2/ gemergt werden — eine Datei auf oberster Ebene in dem Repository der Bibliothek wird also zu einer Datei auf oberster Ebene des Trees libgit2/, der wiederum Teil eines Repositorys ist.

Git verfügt über ein Kommando, um Subtree-Merges zu verwalten.⁠^[86] Dabei müssen Sie immer explizit durch -P <prefix> angeben, auf welches Unterverzeichnis Sie sich beziehen. Um die libgit2 in Version 0.8.0 zu importieren, verwenden Sie:

Das Kommando lädt automatisch alle benötigten Commits herunter und erzeugt einen Merge-Commit, der alle Dateien der libgit2 unterhalb des Verzeichnisses libgit2/ erstellt. Der Merge-Commit verknüpft nun die bisherige Versionsgeschichte mit der der libgit2 (dadurch, dass ein Original-Commit referenziert wird und der wiederum andere Commits referenziert).

Dieses Vorgehen hat nun zur Folge, dass in Ihrem Repository von nun an alle relevanten Commits der libgit2 vorhanden sind. Ihr Repository hat also nun zwei Root-Commits (siehe auch Multi-Root-Repositories in Section 4.7, “Mehrere Root-Commits”).

Die Dateien liegen nun untrennbar mit dem Projekt verbunden vor. Ein git clone dieses Repositorys würde auch alle Dateien unterhalb von libgit2 übertragen.⁠^[87]

Was passiert nun, wenn Sie ein “Upgrade” auf v0.10.0 machen wollen? Verwenden Sie dafür das pull-Kommando von git subtree:

Beachten Sie: Da die Original-Commits der libgit2 vorliegen, ändern diese Commits auch scheinbar Dateien auf oberster Ebene (z.B. `COPYING`, wenn Sie per git log --name-status die Versionsgeschichte untersuchen). Tatsächlich werden diese Änderungen aber in libgit2 ausgeführt — dafür ist der jeweilige Merge-Commit verantwortlich, der die Trees entsprechend ausrichtet.

Die Frage “Submodules oder Subtrees?” lässt sich nicht generell, sondern nur von Fall zu Fall beantworten. Ausschlaggebendes Kriterium sollte die Zugehörigkeit des Unterprojektes zu dem übergeordneten sein: Wenn Sie fremde Software einbinden, dann vermutlich eher als Submodule, eigene mit begrenztem Aufkommen an Commits und einer direkten Relation zum Hauptprojekt eher als Subtree.

Beispielsweise müssen Sie bei der Installation von CGit (siehe Section 7.5, “CGit – CGI for Git”) ein Submodule initialisieren und updaten, um die libgit.a zu kompilieren. CGit benötigt also den Sourcecode von Git, will aber nicht die Entwicklungsgeschichte mit der von Git verschmelzen (die im Vergleich wenigen CGit-Commits würden darin auch untergehen!). Sie können aber CGit auch gegen eine andere Git-Version kompilieren, wenn Sie das möchten — die Flexibilität des Unter-Repositorys bleibt gewahrt.

Der grafische Repository-Browser Gitk hingegen wird als Subtree verwaltet. Er wird in git://ozlabs.org/~paulus/gitk entwickelt, aber im Haupt-Git-Repository mit der Subtree-Merge-Strategie unterhalb von gitk-git/ eingebunden.

Der Maintainer einer Software muss einen guten Überblick über die Features haben, die aktiv entwickelt und bald integriert werden sollen. In den meisten Entwicklungsmodellen graduieren Commits von einem Branch auf den nächsten — im oben vorgestellten Modell zunächst aus den pu-Branches nach next und dann nach master.

Zunächst sollten Sie Ihre lokalen Branches immer aufräumen, um nicht den Überblick zu verlieren. Dabei hilft besonders das Kommando git branch --merged master, das alle Branches auflistet, die schon vollständig in master (oder einen anderen Branch) integriert sind. Diese können Sie in der Regel löschen.

Um einen groben Überblick zu erhalten, welche Aufgaben anstehen, empfiehlt es sich, git show-branch einzusetzen. Ohne weitere Argumente listet es alle lokalen Branches auf, jeden mit einem Ausrufezeichen (!) in eigener Farbe. Der aktuelle Branch erhält einen Stern (). Unterhalb der Ausgabe werden alle Commits ausgegeben sowie für jeden Branch in der jeweiligen Spalte ein Plus (+) bzw. ein Stern (), wenn der Commit Teil des Branches ist. Ein Minus (-) signalisiert Merge-Commits.

Es werden nur so viele Commits gezeigt, bis eine gemeinsame Merge-Basis aller Commits gefunden wird (im Beispiel: master~4). Wollen Sie nicht alle Branches gleichzeitig untersuchen, sondern z.B. nur die Branches unter pu/, dann geben Sie dies explizit als Argument an. --topics <branch> bestimmt <branch> als Integrations-Zweig, dessen Commits nicht explizit angezeigt werden.

Das folgende Kommando zeigt Ihnen also alle Commits aller pu-Branches und deren Relation zu master:

Das Kommando git show-branch erkennt allerdings nur gleiche, das heißt identische Commits. Wenn Sie einen Commit per git cherry-pick in einen anderen Branch übernehmen, sind die Änderungen fast die gleichen, git show-branch würde dies aber nicht erkennen, da sich die SHA-1-Summe des Commits ändert.

Für diese Fälle ist das Tool git cherry zuständig. Es verwendet intern das kleine Tool git-patch-id, das einen Commit auf seine bloßen Änderungen reduziert. Dabei werden Whitespace-Änderungen sowie die kontextuelle Position der Hunks (Zeilennummern) ignoriert. Das Tool liefert also für Patches, die essentiell die gleiche Änderung einbringen, die gleiche ID.

In der Regel wird git cherry eingesetzt, wenn sich die Frage stellt: Welche Commits wurden schon in den Integrations-Branch übernommen? Dafür wird das Kommando git cherry -v <upstream> <topic> verwendet: Es listet alle Commits aus <topic> auf, und stellt ihnen ein Minus (-) voran, wenn sie schon in <upstream> sind, ansonsten ein Plus (+). Das sieht z.B. so aus:

Zwei der Patches wurden schon nach master übernommen. Das erkennt git cherry, obwohl sich die Commit-IDs dabei geändert haben.

Git bietet die folgenden zwei nützlichen Werkzeuge, um ein Release vorzubereiten:

Zu einem guten Release gehört ein sogenanntes Changelog, also eine Zusammenfassung der wichtigsten Neuerungen inklusive Danksagungen an Personen, die Hilfe beigesteuert haben. Hier kommt git shortlog zum Einsatz. Das Kommando zeigt die jeweiligen Autoren, wie viele Commits jeder gemacht hat und die Commit-Messages der einzelnen Commits. So ist sehr gut ersichtlich, wer was gemacht hat.

Mit der Option --numbered bzw. -n wird die Ausgabe, statt alphabetisch, nach der Anzahl der Commits sortiert. Mit --summary bzw. -s fallen die Commit-Nachrichten weg.

Sehen Sie aber im Zweifel davon ab, einfach die Ausgabe von git log oder git shortlog in die Datei CHANGELOG zu schreiben. Gerade bei vielen, technischen Commits ist das Changelog dann nicht hilfreich (wen diese Informationen interessieren, der kann immer im Repository nachschauen). Sie können aber die Ausgabe als Grundlage nehmen, unwichtige Änderungen löschen und die restlichen zu sinnvollen Gruppen zusammenfassen.

Das Kommando git archive hilft beim Erstellen eines Quellcode-Archivs. Das Kommando beherrscht sowohl das Tar- als auch das Zip-Format. Zusätzlich können Sie mit der Option --prefix= ein Präfix für die zu speichernden Dateien setzen. Die oberste Ebene des Repositorys wird dann unterhalb dieses Präfix abgelegt, üblicherweise der Name und die Versionsnummer der Software:

Als zwingendes Argument erwartet das Kommando einen Commit (bzw. einen Tree), der als Archiv gepackt werden soll. Im o.g. Beispiel ist das HEAD. Es hätte aber auch eine Commit-ID, eine Referenz (Branch oder Tag) oder direkt ein Tree-Objekt sein können.⁠^[91]

Auch hier können Sie git describe einsetzen, nachdem Sie einen Release-Commit getaggt haben. Bei einem geeigneten Tag-Schema <name>-<X.Y.Z> wie oben reicht dann folgendes Kommando:

Es kann sein, dass nicht alle Dateien, die Sie in Ihrem Git-Repository verwalten, auch in den Quellcode-Archiven vorkommen sollten, z.B. die Projekt-Webseite. Sie können zusätzlich noch Pfade angeben — um also das Archiv auf das Verzeichnis src und die Dateien LICENSE und README zu beschränken, verwenden Sie:

Git speichert, sofern Sie einen Commit als Argument angeben, die SHA-1-Summe mit im Archiv ab. Im Tar-Format wird dies als Pax-Header-Eintrag mit eingespeichert, den Git mit dem Kommando git get-tar-commit-id wieder auslesen kann:

In Zip-Dateien speichert Git die SHA-1-Summe einfach im Kommentarfeld:

Git ist auf dezentrale Verwaltung der Repositories ausgelegt; die kleinste Einheit, um Änderungen zwischen Repositories auszutauschen, sind Commits. Da sich aber zwischen zwei Versionen einer Software bisweilen tausende von Commits ansammeln und eine einzelne, commitweise Übertragung viel Overhead erzeugen würde, werden Commits vor der Übertragung zu sogenannten Packfiles zusammengefasst. Diese Packfiles sind ein simples, aber effektives Format.⁠^[92] Sie werden auch verwendet, um (ältere) Commits auf der Festplatte platzsparend zu lagern (git gc bzw. git repack, siehe Section B.1, “Aufräumen”).

Diese Packfiles werden in der Regel über das Git-Protokoll übertragen, das standardmäßig auf Port 9418/TCP läuft. Das Git-Protokoll ist vom Design her bewusst sehr einfach gehalten und bietet nur wenige Funktionen, die unmittelbar mit der Struktur von Git zu tun haben: Welche Daten gesendet oder empfangen werden sollen sowie eine Möglichkeit für Sender- und Empfängerseite, sich auf die kleinstmögliche Datenmenge zu einigen, die übertragen werden muss, um beide Seiten zu synchronisieren.

Das Git-Protokoll enthält daher keine Möglichkeit der Authentifizierung. Stattdessen verwendet Git eine bereits vorhandene, sichere und einfache Authentifizierungsstruktur: SSH, die 'Secure Shell'.

Während das Git-Protokoll also unverschlüsselt und in Rohform für anonymen Lesezugriff uneingeschränkt verwendet werden kann, funktioniert ein Schreiben bzw. Hochladen über das Git-Protokoll nur, wenn dies über SSH erfolgt.

Des Weiteren unterstützt Git auch den Transport über HTTP(S), FTP(S), sowie Rsync. Zwar gilt die Unterstützung für letzteres mittlerweile als deprecated, es sollte also nicht mehr benutzt werden; für HTTP(S) finden sich aber gewisse Anwendungsfälle: In besonders restriktiven Umgebungen mit sehr einschränkenden Firewall-Regeln kann man eventuell über HTTP(S) (also nur auf Port 80 bzw. 443) auf ein Repository lesend wie schreibend zugreifen. Plattformen wie GitHub (siehe Chapter 11, GitHub) bieten HTTPS daher als Standard-Transportmethode an.

Wollen Sie Änderungen an Repositories auf dem gleichen Rechner synchronisieren, muss dies nicht über Umwege erfolgen: Git kommuniziert direkt über Unix-Pipes mit der Gegenseite, handelt eine gemeinsame Basis aus und synchronisiert die Daten. (Dafür ist es natürlich nötig, dass der Nutzer, der das Git-Kommando aufruft, zumindest Leseberechtigung auf die Packfiles des anderen Repositorys hat.)

Bisher haben Sie vermutlich größtenteils mit Git-Repositories gearbeitet, die Working Tree und Repository in einem waren: Die repositoryinternen Daten werden in einem Unterverzeichnis .git gespeichert, alle anderen Dateien gehören dem Working Tree an, d.h. Sie können sie editieren, während Git die Veränderung an diesen Dateien beobachtet und abspeichert (Tracking).

Ein sogenanntes Bare Repository, also ein “bloßes” Repository, hat keinen zugeordneten Working Tree. Es enthält nur die Dateien und Verzeichnisse, die in einem “regulären” Repository unterhalb von .git gespeichert sind.

Ein solches Bare Repository erstellen Sie durch git init --bare. Schauen Sie sich den Unterschied zwischen den beiden Möglichkeiten an:

Um ein Backup eines Ihrer normalen Repositories anzulegen, können Sie (z.B. auf einem USB-Stick) ein neues Bare Repository erstellen und alle Ihre Referenzen (und damit alle Ihre Commits) hochladen:

Bei git init werden die Dateien in der Regel mit Lese- und Schreibberechtigung entsprechend der gesetzten umask angelegt. Für den Endanwender ist dies auch eine günstige Wahl. Wollen Sie aber ein Repository auf einem Server einrichten, dann können Sie mit der Option --shared angeben, wer (auf Dateisystemebene) auf das Repository zugreifen kann.

Wenn Sie ein Repository mit --shared initialisieren, wird automatisch die Option receive.denyNonFastForwards gesetzt. Sie verhindert, dass Commits hochgeladen werden, die nicht per Fast-Forward integriert werden können (selbst, wenn der Nutzer dies explizit will via git push -f).

In der Regel kann der Schreib-Zugriff auf Git-Repositories, die auf einem anderen Rechner liegen, nur per SSH erfolgen. Allerdings ist es im Allgemeinen nicht wünschenswert, einem Nutzer, der Zugriffsrechte auf ein Repository erhalten soll, auch gleich Nutzerrechte auf dem ganzen System einzuräumen.

Dieses Problem umgeht Git mit dem mitgelieferten Programm git-shell. Es funktioniert wie eine Shell, erlaubt aber nur die Ausführung von vier Git-Kommandos, die für das Hoch- und Runterladen von Packfiles zuständig sind. Interaktive Benutzung oder Ausführung anderer Kommandos verweigert die Shell, sofern Sie nicht den “Interaktiven Modus” der Shell explizit aktivieren — siehe dafür die Man-Page git-shell(1).

Wenn Sie einen neuen Benutzer anlegen und ihm z.B. per chsh <user> die Git-Shell zuweisen, kann er sich nicht per SSH einloggen, aber auf alle Git-Repositories, auf denen er Schreibberechtigung hat, Commits hochladen.

Es ist ein wesentlicher Vorteil, dass Git SSH als verschlüsselten und authentifizierten Transportkanal verwendet, denn die meisten Nutzer haben bereits ein Schlüsselpaar (öffentlich/privat), mit dem sie sich auf anderen Rechnern einloggen.

Anstatt also umständlich Passwörter für Accounts zu vergeben (und dann zu versenden), kann ein Systemadministrator den Zugriff auf Git-Repositories auf Nutzer limitieren, die sich gegen öffentliche SSH-Schlüssel authentifizieren. Das spart dem Nutzer Zeit (durch die möglicherweise wegfallende wiederholte Eingabe eines Passworts), aber auch dem Administrator, der sich nicht um Passwortänderungen kümmern muss (die durch Einsatz der Git-Shell nicht ohne weiteres möglich wären).

Im Folgenden wollen wir beispielhaft die Kommandos entwickeln, mit denen Sie zwei Nutzer max und moritz auf Ihrem System einrichten und sie auf dem gleichen Repository arbeiten lassen.

Zunächst müssen wir ein Repository einrichten, auf das die beiden später zugreifen wollen. Unter der Annahme, dass vielleicht später weitere Repositories folgen sollen, erstellen wir eine Unix-Gruppe git (generell für Git-Nutzer) und ein Verzeichnis /var/repositories mit Leseberechtigung für Mitglieder der Gruppe git, außerdem eine Gruppe git-beispiel und ein entsprechendes Verzeichnis, schreibbar nur für Mitglieder von git-beispiel, in dem sich dann später das Repository befindet:

Wir erstellen auch gleich ein Repository in dem zuletzt angelegten Verzeichnis:

Als nächstes erstellen wir die beiden Nutzer. Beachten Sie, dass bei diesem Aufruf kein Homeverzeichnis für die Nutzer unter /home/ erstellt wird. Außerdem werden beide der Gruppe git und git-beispiel hinzugefügt:

Als nächstes müssen wir den Nutzern per passwd noch jeweils ein Passwort zuweisen, damit sie sich per SSH einloggen können. Anschließend können die neuen Nutzer nun gemeinsam an einem Projekt entwickeln. Das Remote fügen Sie wie folgt hinzu:

Alle weiteren Nutzer, die an diesem Projekt mitarbeiten wollen, müssen der Gruppe git-beispiel angehören. Dieser Ansatz basiert also wesentlich auf der Nutzung von Unix-Gruppen und Unix-Nutzern. Allerdings will ein Server-Admin in der Regel nicht nur Git anbieten, sondern diverse Services. Und die Nutzerverwaltung vollständig über Unix-Gruppen zu regeln, ist eher unflexibel.

Die Installation von Gitolite ist einfach. Sie müssen dafür nur Ihren Public-Key bereithalten, um sich als Administrator eintragen zu können. Root-Rechte benötigen Sie nicht, es sei denn, Sie müssen den Nutzer git erst erstellen.⁠^[95] Überspringen Sie also den nachfolgenden Schritt, wenn Sie bereits einen solchen Nutzer erstellt haben.

Zunächst erstellen Sie einen Nutzer auf dem Rechner, der als Git-Server arbeiten soll (im Folgenden <server>). In der Regel wird dieser Nutzer git genannt, Sie können ihn aber auch anders nennen (z.B. `gitolite`). Als Homeverzeichnis können Sie /home/git angeben oder auch, wie hier im Beispiel, etwas wie /var/git:

Werden Sie nun zum Nutzer git. Gitolite braucht die Verzeichnisse .ssh/ und bin/, also müssen wir diese erstellen:

Klonen Sie nun das Gitolite-Repository, und installieren Sie einen Symlink nach bin (dies ist schon die ganze Installation):

Sie können nun Gitolite konfigurieren und Ihren öffentlichen Schlüssel eintragen, mit dem Sie die Gitolite-Konfiguration verwalten wollen:

Überprüfen Sie auf dem Rechner, auf dem Sie normalerweise arbeiten (und wo Sie den entsprechenden privaten Schlüssel hinterlegt haben), ob Gitolite funktioniert:

Sie sollten erkennen, dass Sie mit Ihrem Key Lese- und Schreibberechtigung auf dem Repository gitolite-admin besitzen. Dieses klonen Sie nun auf Ihren Computer:

Das Repository enthält die gesamte Konfiguration für Gitolite. Sie checken Ihre Änderungen dort ein und laden Sie per git push hoch: Der Server aktualisiert automatisch die Einstellungen.

Im Gitolite-Admin-Verzeichnis befinden sich zwei Unterverzeichnisse, conf und keydir. Um Gitolite einen neuen Nutzer vorzustellen, müssen Sie dessen SSH-Schlüssel unter keydir/<nutzer>.pub ablegen. Hat der Nutzer mehrere Schlüssel, können Sie diese in einzelnen Dateien vom Format <nutzer>@<beschreibung>.pub ablegen:

Vergessen Sie nicht, mit git add keydir und einem anschließenden git commit die neuen Schlüssel einzuchecken. Um diese der Gitolite-Installation bekannt zu machen, müssen Sie außerdem die Commits durch git push hochladen.

Danach können Sie diesem Nutzernamen in der Konfigurationsdatei conf/gitolite.conf Berechtigungen zuweisen.

Über sogenannte Makros können Sie sich viel administrativen Aufwand bzw. Tipparbeit sparen. Sie können Gruppen (von Nutzern oder Repositories) zusammenfassen, z.B.

Diese Makros werden auch rekursiv ausgewertet. Bei der Definition muss nicht klar sein, ob es sich um Nutzer oder Repositories handelt; die Makros werden erst zur Laufzeit ausgewertet. So können Sie Gruppen aus anderen Gruppen zusammensetzen:

Es gibt eine spezielle Gruppe @all, die, je nach Kontext, alle Nutzer oder alle Repositories enthält.

Ein (oder mehrere) Repositories können Sie wie folgt konfigurieren:

R und W stehen für Lese- bzw. Schreibzugriff. Das Plus bedeutet, dass auch ein forciertes Hochladen erlaubt ist (non-fast-forward, also auch das Löschen von Commits).

Für ein Repository können natürlich mehrere solcher Zeilen eingetragen werden. In einem kleinen Projekt könnte es Maintainer, weitere Entwickler und Tester geben. Dann könnten die Zugriffsrechte wie folgt geregelt werden:

So haben die Tester nur Lesezugriff, während die Entwickler zwar neue Commits hochladen dürfen, aber nur, wenn diese per fast-forward integriert werden können. Die Hauptmaintainer dürfen “alles”.

Diese Zeilen werden sequentiell abgearbeitet. Trifft die Zeile für einen Nutzer zu, so autorisiert Gitolite den Nutzer und stattet ihn mit den entsprechenden Rechten aus. Sofern keine Zeile auf den Nutzer zutrifft, wird er zurückgewiesen und darf an dem Repository nichts verändern.

Ein Nutzer kann alle seine Berechtigungen anzeigen lassen, indem er sich einfach per SSH auf dem Git-Server einloggt. Direkt nach der Installation sieht dies für den Administrator dann so aus:

Sofern Sie später ein webbasiertes Tool installieren wollen, mit dem man die Git-Repositories durchstöbern kann, sollten Sie auch gleich einen Verantwortlichen benennen und das Projekt beschreiben:

Damit dies funktioniert, müssen Sie allerdings erst aktivieren, dass Gitolite diese Config-Einstellungen setzen darf: Das geschieht auf dem Server, wo Gitolite installiert ist, in der Datei .gitolite.rc: Tragen Sie dort unter dem Schlüssel GIT_CONFIG_KEYS den Wert gitweb\..* ein.